updates

Author: wcharczuk

bind.go

@@ -36,7 +36,8 @@ func Bind[A, B any](scope Scope, input Incr[A], fn func(Scope, A) Incr[B]) BindI
 
 // BindContext is like Bind but allows the bind delegate to take a context and return an error.
 //
-// If an error returned, the bind is aborted and the error listener(s) will fire for the node.
+// If an error returned, the bind is aborted, the error listener(s) will fire for the node, and the
+// computation will stop.
 func BindContext[A, B any](scope Scope, input Incr[A], fn func(context.Context, Scope, A) (Incr[B], error)) BindIncr[B] {
 	o := &bindIncr[A, B]{
 		n:     NewNode("bind"),
@@ -50,9 +51,11 @@ func BindContext[A, B any](scope Scope, input Incr[A], fn func(context.Context,
 	return WithinScope(scope, o)
 }
 
-// BindIncr is a node that implements Bind, which
-// dynamically swaps out entire subgraphs
-// based on input incrementals.
+// BindIncr is a node that implements Bind, which can dynamically swap out
+// subgraphs based on input incrementals changing.
+//
+// BindIncr gives the graph dynamism, but as a result is somewhat expensive to
+// compute and should be used tactically.
 type BindIncr[A any] interface {
 	Incr[A]
 	IStabilize

bind2.go

@@ -13,18 +13,18 @@ func Bind2[A, B, C any](scope Scope, a Incr[A], b Incr[B], fn func(Scope, A, B)
 // Bind2Context lets you swap out an entire subgraph of a computation based
 // on a given set of 2 input incrementals, taking a context and as well returning an error.
 func Bind2Context[A, B, C any](scope Scope, a Incr[A], b Incr[B], fn func(context.Context, Scope, A, B) (Incr[C], error)) BindIncr[C] {
-	m := Map2(scope, a, b, func(av A, bv B) Tuple2[A, B] {
-		return Tuple2[A, B]{av, bv}
+	m := Map2(scope, a, b, func(av A, bv B) tuple2[A, B] {
+		return tuple2[A, B]{av, bv}
 	})
-	bind := BindContext[Tuple2[A, B], C](scope, m, func(ctx context.Context, bs Scope, tv Tuple2[A, B]) (Incr[C], error) {
+	bind := BindContext[tuple2[A, B], C](scope, m, func(ctx context.Context, bs Scope, tv tuple2[A, B]) (Incr[C], error) {
 		return fn(ctx, scope, tv.A, tv.B)
 	})
 	bind.Node().SetKind("bind2")
 	return bind
 }
 
-// Tuple2 is a tuple of values.
-type Tuple2[A, B any] struct {
+// tuple2 is a tuple of values.
+type tuple2[A, B any] struct {
 	A A
 	B B
 }

bind3.go

@@ -13,18 +13,18 @@ func Bind3[A, B, C, D any](scope Scope, a Incr[A], b Incr[B], c Incr[C], fn func
 // Bind3Context lets you swap out an entire subgraph of a computation based
 // on a given set of 3 input incrementals, taking a context and as well returning an error.
 func Bind3Context[A, B, C, D any](scope Scope, a Incr[A], b Incr[B], c Incr[C], fn func(context.Context, Scope, A, B, C) (Incr[D], error)) BindIncr[D] {
-	m := Map3(scope, a, b, c, func(av A, bv B, cv C) Tuple3[A, B, C] {
-		return Tuple3[A, B, C]{av, bv, cv}
+	m := Map3(scope, a, b, c, func(av A, bv B, cv C) tuple3[A, B, C] {
+		return tuple3[A, B, C]{av, bv, cv}
 	})
-	bind := BindContext[Tuple3[A, B, C], D](scope, m, func(ctx context.Context, bs Scope, tv Tuple3[A, B, C]) (Incr[D], error) {
+	bind := BindContext[tuple3[A, B, C], D](scope, m, func(ctx context.Context, bs Scope, tv tuple3[A, B, C]) (Incr[D], error) {
 		return fn(ctx, scope, tv.A, tv.B, tv.C)
 	})
 	bind.Node().SetKind("bind3")
 	return bind
 }
 
-// Tuple3 is a tuple of values.
-type Tuple3[A, B, C any] struct {
+// tuple3 is a tuple of values.
+type tuple3[A, B, C any] struct {
 	A A
 	B B
 	C C

bind4.go

@@ -13,18 +13,18 @@ func Bind4[A, B, C, D, E any](scope Scope, a Incr[A], b Incr[B], c Incr[C], d In
 // Bind4Context lets you swap out an entire subgraph of a computation based
 // on a given set of 4 input incrementals, taking a context and as well returning an error.
 func Bind4Context[A, B, C, D, E any](scope Scope, a Incr[A], b Incr[B], c Incr[C], d Incr[D], fn func(context.Context, Scope, A, B, C, D) (Incr[E], error)) BindIncr[E] {
-	m := Map4(scope, a, b, c, d, func(av A, bv B, cv C, dv D) Tuple4[A, B, C, D] {
-		return Tuple4[A, B, C, D]{av, bv, cv, dv}
+	m := Map4(scope, a, b, c, d, func(av A, bv B, cv C, dv D) tuple4[A, B, C, D] {
+		return tuple4[A, B, C, D]{av, bv, cv, dv}
 	})
-	bind := BindContext[Tuple4[A, B, C, D], E](scope, m, func(ctx context.Context, bs Scope, tv Tuple4[A, B, C, D]) (Incr[E], error) {
+	bind := BindContext[tuple4[A, B, C, D], E](scope, m, func(ctx context.Context, bs Scope, tv tuple4[A, B, C, D]) (Incr[E], error) {
 		return fn(ctx, scope, tv.A, tv.B, tv.C, tv.D)
 	})
 	bind.Node().SetKind("bind4")
 	return bind
 }
 
-// Tuple4 is a tuple of values.
-type Tuple4[A, B, C, D any] struct {
+// tuple4 is a tuple of values.
+type tuple4[A, B, C, D any] struct {
 	A A
 	B B
 	C C

graph.go

@@ -7,14 +7,17 @@ import (
 	"time"
 )
 
-// New returns a new graph state, which is the type that
-// represents the shared state of a computation graph.
+// New returns a new graph state, which is the type that represents the
+// shared state of a computation graph.
+//
+// You can pass configuration options as `GraphOption` to customize settings
+// within the graph, such as what the maximum "height" a node can be.
 //
 // This is the entrypoint for all stabilization and computation
-// operations.
+// operations, and generally the Graph will be passed to node constructors.
 //
-// Nodes you initialize the graph with will be "observed" before
-// the graph is returned, saving that step later.
+// Nodes you initialize the graph with will need to be be observed by
+// an `Observer` before you can stabilize them.
 func New(opts ...GraphOption) *Graph {
 	options := GraphOptions{
 		MaxHeight: DefaultMaxHeight,
@@ -61,12 +64,12 @@ var (
 	_ Scope = (*Graph)(nil)
 )
 
-// Graph is the state that is shared across nodes.
+// Graph is the state that is shared across nodes in a computation graph.
 //
-// You should instantiate this type with `New()`.
+// You should instantiate this type with the `New()` function.
 //
-// It is important to note that most operations on the graph are _not_ concurrent
-// safe and you should use your own mutex to synchronize access to internal state.
+// The graph holds information such as, how many stabilizations have happened,
+// what node are currently observed, and what nodes need to be recomputed.
 type Graph struct {
 	// id is a unique identifier for the graph
 	id Identifier

map_n.go

@@ -27,10 +27,10 @@ func MapNContext[A, B any](scope Scope, fn MapNContextFunc[A, B], inputs ...Incr
 	return WithinScope(scope, o)
 }
 
-// MapNFunc is the function that the ApplyN incremental applies.
+// MapNFunc is the function that the MapN incremental applies.
 type MapNFunc[A, B any] func(...A) B
 
-// MapNContextFunc is the function that the ApplyN incremental applies.
+// MapNContextFunc is the function that the MapNContext incremental applies.
 type MapNContextFunc[A, B any] func(context.Context, ...A) (B, error)
 
 // MapNIncr is a type of incremental that can add inputs over time.