more doc strings

Author: wcharczuk

bind.go

@@ -25,9 +25,9 @@ import (
 // as a "child" of (b), preventing it from being considered part of the
 // overall computation unless it's referenced by another node in the graph.
 //
-// More information is available at:
+// More information is available at in the [Janestreet docs].
 //
-//	https://github.com/janestreet/incremental/blob/master/src/incremental_intf.ml
+// [Janestreet Docs]: https://github.com/janestreet/incremental/blob/master/src/incremental_intf.ml
 func Bind[A, B any](scope Scope, input Incr[A], fn BindFunc[A, B]) BindIncr[B] {
 	return BindContext(scope, input, func(_ context.Context, bs Scope, va A) (Incr[B], error) {
 		return fn(bs, va), nil

bind_if.go

@@ -4,8 +4,10 @@ import "context"
 
 // BindIf lets you swap out an entire subgraph of a computation based
 // on a given boolean incremental predicate.
+//
+// It is largely "macro" for a Bind that takes an input bool incremental.
 func BindIf[A any](scope Scope, p Incr[bool], fn func(context.Context, Scope, bool) (Incr[A], error)) BindIncr[A] {
-	b := BindContext[bool, A](scope, p, fn)
+	b := BindContext(scope, p, fn)
 	b.Node().SetKind("bind_if")
 	return b
 }

detect_cycle_if_linked.go

@@ -5,9 +5,8 @@ import "fmt"
 // DetectCycleIfLinked determines if adding a given input to a given
 // child would cause a graph cycle.
 //
-// It is a low-level utility function that should be used
-// in special cases; the vast majority of direct use cases
-// for the incremental library cannot create graph cycles.
+// It is a low-level utility function that should be used in special cases; the vast
+// majority of situations outside very esoteric [Bind] use cases cannot create cycles.
 func DetectCycleIfLinked(child, parent INode) error {
 	if child == nil || parent == nil {
 		return nil

expert_graph.go

@@ -16,22 +16,50 @@ func ExpertGraph(g *Graph) IExpertGraph {
 // Note there are no compatibility guarantees on this interface
 // and you should use this interface at your own risk.
 type IExpertGraph interface {
+	// SetID sets the identifier for the [Graph].
 	SetID(Identifier)
+
+	// NumNodes returns the number of nodes the [Graph] is tracking.
 	NumNodes() uint64
+
+	// NumNodesRecomputed returns the number of nodes the [Graph] has
+	// recomputed in its lifetime.
 	NumNodesRecomputed() uint64
+
+	// NumNodesChanged returns the number of nodes the [Graph] has
+	// updated the value of in its lifetime.
 	NumNodesChanged() uint64
+
+	// NumObservers returns the current count of observers the [Graph] is tracking.
 	NumObservers() uint64
+
+	// StabilizationNum returns the current stabilization number of the [Graph].
 	StabilizationNum() uint64
+
+	// SetStabilizationNumber sets the current stabilization number, specifically
+	// in situations where you're restoring graph state.
 	SetStabilizationNum(uint64)
 
+	// RecomputeHeapAdd directly adds a varadic array of nodes to the recompute heap.
 	RecomputeHeapAdd(...INode)
+
+	// RecomputeHeapLen returns the current length of the recompute heap.
 	RecomputeHeapLen() int
+
+	// RecomputeHeapIDs returns the node identifiers that are held in the recompute heap.
+	//
+	// This is useful when saving the state of a [Graph] to an external store.
 	RecomputeHeapIDs() []Identifier
 
-	AddChild(INode, INode) error
-	RemoveParent(INode, INode)
+	// AddChild associates a child node to a parent.
+	AddChild(child INode, parent INode) error
+	// RemoveParent removes the association between a child and a parent.
+	RemoveParent(child INode, parent INode)
 
+	// ObserveNode implements the observe steps usually handled by [Observe] for custom nodes.
 	ObserveNode(IObserver, INode) error
+
+	// UnobserveNode implements the unobserve steps usually handled by observers.
 	UnobserveNode(IObserver, INode)
 }
 

expert_var.go

@@ -14,7 +14,7 @@ func ExpertVar[A any](v VarIncr[A]) IExpertVar[A] {
 // and you should use this interface at your own risk.
 type IExpertVar[A any] interface {
 	// SetInternalValue allows you to set the underlying value of a var
-	// _without_ marking it as stale or needing to be recomputed.
+	// without marking it as stale.
 	//
 	// This can be useful when deserializing graphs from some other state.
 	SetInternalValue(A)

freeze.go

@@ -6,7 +6,11 @@ import (
 )
 
 // Freeze yields an incremental that takes the value of an
-// input incremental and doesn't change thereafter.
+// input incremental on the first stabilization and
+// doesn't change thereafter.
+//
+// Stabilization propagates through this node even
+// after the first stabilization.
 func Freeze[A any](scope Scope, i Incr[A]) Incr[A] {
 	return WithinScope(scope, &freezeIncr[A]{
 		n: NewNode("freeze"),

return.go

@@ -6,8 +6,8 @@ import (
 
 // Return yields a constant incremental for a given value.
 //
-// Note that it does not implement `IStabilize` and is effectively
-// always the same value (and treated as such).
+// Note that it does not implement [IStabilize] and is effectively
+// always the same value, and never causes recomputations.
 func Return[A any](scope Scope, v A) Incr[A] {
 	return WithinScope(scope, &returnIncr[A]{
 		n: NewNode("return"),