Merge pull request #238 from cube2222/documentation_update

Documentation update

README.md

@@ -334,6 +334,8 @@ Documentation for the available functions: https://github.com/cube2222/octosql/w
 
 Documentation for the available aggregates: https://github.com/cube2222/octosql/wiki/Aggregate-Documentation
 
+Documentation for the available triggers: https://github.com/cube2222/octosql/wiki/Trigger-Documentation
+
 Documentation for the available table valued functions: https://github.com/cube2222/octosql/wiki/Table-Valued-Functions-Documentation
 
 The SQL dialect documentation: TODO ;) in short though:

docs/docs.go

@@ -17,6 +17,31 @@ type Documentation interface {
  render(w io.Writer, headerLevel int, indentation int, parentIsList bool)
 }
 
+type tableOfContents struct {
+ names []string
+ hashes []string
+}
+
+func (d *tableOfContents) render(w io.Writer, headerLevel int, indentation int, parentIsList bool) {
+ for i := 0; i <= headerLevel; i++ {
+ fmt.Fprint(w, "#")
+ }
+ fmt.Fprintf(w, " Table of Contents\n")
+
+ for i := range d.names {
+ fmt.Fprintf(w, "* [%s]", d.names[i])
+ fmt.Fprintf(w, "(#%s)", d.hashes[i])
+
+ if i != len(d.names)-1 {
+ fmt.Fprint(w, "\n")
+ }
+ }
+}
+
+func TableOfContents(names, hashes []string) *tableOfContents {
+ return &tableOfContents{names: names, hashes: hashes}
+}
+
 type body struct {
  elements []Documentation
 }

execution/aggregates/avg.go

@@ -2,11 +2,13 @@ package aggregates
 
 import (
  "context"
+ "fmt"
  "time"
 
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -100,3 +102,12 @@ func (agg *Average) GetValue(ctx context.Context, tx storage.StateTransaction) (
 func (agg *Average) String() string {
  return "avg"
 }
+
+func (agg *Average) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text(fmt.Sprintf("Works like [%s](#%s) and [%s](#%s) combined", agg.underlyingSum.String(), agg.underlyingSum.String(), agg.underlyingCount.String(), agg.underlyingCount.String()))),
+ ),
+ )
+}

execution/aggregates/count.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -88,3 +89,12 @@ func (agg *Count) GetValue(ctx context.Context, tx storage.StateTransaction) (oc
 func (agg *Count) String() string {
  return "count"
 }
+
+func (agg *Count) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Counts elements in the group.")),
+ ),
+ )
+}

execution/aggregates/distinct.go

@@ -7,6 +7,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/execution"
  "github.com/cube2222/octosql/storage"
 )
@@ -96,3 +97,12 @@ func (agg *Distinct) GetValue(ctx context.Context, tx storage.StateTransaction)
 func (agg *Distinct) String() string {
  return fmt.Sprintf("%s_distinct", agg.underlying.String())
 }
+
+func (agg *Distinct) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text(fmt.Sprintf("Works like [%s](#%s), only taking into account distinct elements per group.", agg.underlying.String(), agg.underlying.String()))),
+ ),
+ )
+}

execution/aggregates/docgen/main.go

@@ -0,0 +1,41 @@
+package main
+
+import (
+ "os"
+ "sort"
+
+ "github.com/cube2222/octosql/docs"
+ "github.com/cube2222/octosql/execution/aggregates"
+)
+
+func main() {
+ var aggregateNames []string
+ for k := range aggregates.AggregateTable {
+ aggregateNames = append(aggregateNames, k)
+ }
+ sort.Strings(aggregateNames)
+
+ aggregateDocs := make([]docs.Documentation, len(aggregateNames))
+ for i, name := range aggregateNames {
+ aggregateDocs[i] = aggregates.AggregateTable[name]().Document()
+ }
+
+ var body []docs.Documentation
+
+ body = append(body, docs.TableOfContents(aggregateNames, aggregateNames))
+ body = append(body, docs.Divider())
+
+ for i := range aggregateDocs {
+ body = append(body, aggregateDocs[i])
+ if i != len(aggregateDocs)-1 {
+ body = append(body, docs.Divider())
+ }
+ }
+
+ page := docs.Section(
+ "Aggregate Documentation",
+ docs.Body(body...),
+ )
+
+ docs.RenderDocumentation(page, os.Stdout)
+}

execution/aggregates/first.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -116,3 +117,12 @@ func (agg *First) GetValue(ctx context.Context, tx storage.StateTransaction) (oc
 func (agg *First) String() string {
  return "first"
 }
+
+func (agg *First) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Takes the first received element in the group.")),
+ ),
+ )
+}

execution/aggregates/key.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -106,3 +107,12 @@ func (agg *Key) GetValue(ctx context.Context, tx storage.StateTransaction) (octo
 func (agg *Key) String() string {
  return "key"
 }
+
+func (agg *Key) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Stores aggregated key")),
+ ),
+ )
+}

execution/aggregates/last.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -116,3 +117,12 @@ func (agg *Last) GetValue(ctx context.Context, tx storage.StateTransaction) (oct
 func (agg *Last) String() string {
  return "last"
 }
+
+func (agg *Last) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Takes the last received element in the group.")),
+ ),
+ )
+}

execution/aggregates/max.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -93,3 +94,12 @@ func (agg *Max) GetValue(ctx context.Context, tx storage.StateTransaction) (octo
 func (agg *Max) String() string {
  return "max"
 }
+
+func (agg *Max) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Takes the maximum element in the group. Works with any type.")),
+ ),
+ )
+}

execution/aggregates/min.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -93,3 +94,12 @@ func (agg *Min) GetValue(ctx context.Context, tx storage.StateTransaction) (octo
 func (agg *Min) String() string {
  return "min"
 }
+
+func (agg *Min) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Takes the minimum element in the group. Works with any type.")),
+ ),
+ )
+}

execution/aggregates/sum.go

@@ -6,6 +6,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -184,3 +185,12 @@ func (agg *Sum) GetValue(ctx context.Context, tx storage.StateTransaction) (octo
 func (agg *Sum) String() string {
  return "sum"
 }
+
+func (agg *Sum) Document() docs.Documentation {
+ return docs.Section(
+ agg.String(),
+ docs.Body(
+ docs.Section("Description", docs.Text("Sums Floats, Ints or Durations in the group. You may not mix types.")),
+ ),
+ )
+}

execution/functions/docgen/main.go

@@ -15,12 +15,28 @@ func main() {
  }
  sort.Strings(functionNames)
 
+ // These names have different hashes than name, so we need to create separate 'hashes' slice
+ hashesMap := map[string]string{
+ "*": "", // this is weird, unfortunately it's not working
+ "+": "-1",
+ "/": "-2",
+ }
+
+ hashes := make([]string, len(functionNames))
  functionDocs := make([]docs.Documentation, len(functionNames))
  for i, name := range functionNames {
  functionDocs[i] = functions.FunctionTable[name].Document()
+ hashes[i] = name
+ if hash, ok := hashesMap[name]; ok {
+ hashes[i] = hash
+ }
  }
 
  var body []docs.Documentation
+
+ body = append(body, docs.TableOfContents(functionNames, hashes))
+ body = append(body, docs.Divider())
+
  for i := range functionDocs {
  body = append(body, functionDocs[i])
  if i != len(functionDocs)-1 {

execution/group_by.go

@@ -5,6 +5,7 @@ import (
  "fmt"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 
  "github.com/pkg/errors"
@@ -13,6 +14,7 @@ import (
 type AggregatePrototype func() Aggregate
 
 type Aggregate interface {
+ docs.Documented
  AddValue(ctx context.Context, tx storage.StateTransaction, value octosql.Value) error
  RetractValue(ctx context.Context, tx storage.StateTransaction, value octosql.Value) error
  GetValue(ctx context.Context, tx storage.StateTransaction) (octosql.Value, error)

execution/process.go

@@ -9,6 +9,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -18,6 +19,7 @@ type ProcessFunction interface {
 }
 
 type Trigger interface {
+ docs.Documented
  RecordReceived(ctx context.Context, tx storage.StateTransaction, key octosql.Value, eventTime time.Time) error
  UpdateWatermark(ctx context.Context, tx storage.StateTransaction, watermark time.Time) error
  PollKeysToFire(ctx context.Context, tx storage.StateTransaction, batchSize int) ([]octosql.Value, error)

execution/trigger/counting.go

@@ -7,6 +7,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -20,6 +21,18 @@ func NewCountingTrigger(fireEvery int) *CountingTrigger {
  }
 }
 
+func (ct *CountingTrigger) Document() docs.Documentation {
+ return docs.Section(
+ "Counting Trigger",
+ docs.Body(
+ docs.Section("Description", docs.Text("Triggers after receiving number of records specified in its argument")),
+ docs.Section("Arguments", docs.List(
+ docs.Text("`fireEvery`: frequency of firing")),
+ ),
+ ),
+ )
+}
+
 var toSendPrefix = []byte("$to_send$")
 var keyCountsPrefix = []byte("$key_counts$")
 

execution/trigger/delay.go

@@ -7,6 +7,7 @@ import (
  "github.com/pkg/errors"
 
  "github.com/cube2222/octosql"
+ "github.com/cube2222/octosql/docs"
  "github.com/cube2222/octosql/storage"
 )
 
@@ -22,6 +23,19 @@ func NewDelayTrigger(delay time.Duration, clock func() time.Time) *DelayTrigger
  }
 }
 
+func (dt *DelayTrigger) Document() docs.Documentation {
+ return docs.Section(
+ "Delay Trigger",
+ docs.Body(
+ docs.Section("Description", docs.Text("Every record it receives got send time equal to `clock() + delay`.\nTriggers every record that has send time smaller than time returned by `clock()`.")),
+ docs.Section("Arguments", docs.List(
+ docs.Text("`delay`: duration added to every record received"),
+ docs.Text("`clock`: function returning time")),
+ ),
+ ),
+ )
+}
+
 func (dt *DelayTrigger) RecordReceived(ctx context.Context, tx storage.StateTransaction, key octosql.Value, eventTime time.Time) error {
  timeKeys := NewTimeSortedKeys(tx.WithPrefix(timeSortedKeys))