WIP: docs

Author: djdv

chan.go

@@ -6,6 +6,7 @@ import (
 	"sync"
 )
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func NewChanResponsePair(req *Request) (ResponseEmitter, Response) {
 	r := &chanResponse{
 		req:     req,

command.go

@@ -173,8 +173,8 @@ func (c *Command) call(req *Request, re ResponseEmitter, env Environment) error
 	return cmd.Run(req, re, env)
 }
 
-// Resolve returns the subcommands at the given path
-// The returned set of subcommands starts with this command and therefore is always at least size 1
+// Resolve returns the subcommands at the given path.
+// The returned set of subcommands starts with this command and therefore is always at least size 1.
 func (c *Command) Resolve(pth []string) ([]*Command, error) {
 	cmds := make([]*Command, len(pth)+1)
 	cmds[0] = c
@@ -233,6 +233,10 @@ func (c *Command) GetOptions(path []string) (map[string]Option, error) {
 // DebugValidate checks if the command tree is well-formed.
 //
 // This operation is slow and should be called from tests only.
+//
+// TODO: review this; I don't see any reason this needs to be attached to all `Command`s
+// rather than being a function which takes in `Command`.
+// ValidateCommand(cmd)[]error|<-chan error; called from tests only.
 func (c *Command) DebugValidate() map[string][]error {
 	errs := make(map[string][]error)
 	var visit func(path string, cm *Command)
@@ -348,6 +352,7 @@ func (c *Command) CheckArguments(req *Request) error {
 	return nil
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 type CommandVisitor func(*Command)
 
 // Walks tree of all subcommands (including this one)
@@ -358,6 +363,7 @@ func (c *Command) Walk(visitor CommandVisitor) {
 	}
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func (c *Command) ProcessHelp() {
 	c.Walk(func(cm *Command) {
 		ht := &cm.Helptext
@@ -367,6 +373,7 @@ func (c *Command) ProcessHelp() {
 	})
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func ClientError(msg string) error {
 	return &Error{Code: ErrClient, Message: msg}
 }

command_test.go

@@ -374,9 +374,9 @@ func TestEmitterExpectError(t *testing.T) {
 
 	switch re.errorCount {
 	case 0:
-		t.Errorf("expected SetError to be called")
+		t.Errorf("expected CloseWithError to be called")
 	case 1:
 	default:
-		t.Errorf("expected SetError to be called once, but was called %d times", re.errorCount)
+		t.Errorf("expected CloseWithError to be called once, but was called %d times", re.errorCount)
 	}
 }

doc.go

@@ -26,8 +26,6 @@
 
 	Emitters
 
-
-
 	An emitter has the Emit method, that takes the command's
 	function's output as an argument and passes it to the user.
 
@@ -49,7 +47,6 @@
 
 	Responses
 
-
 	A response is a value that the user can read emitted values
 	from.
 
@@ -60,16 +57,19 @@
 			Next() (interface{}, error)
 		}
 
+	TODO: logic pass; docs are several years out of date.
+	TODO: English pass; <-AME (the whole file needs a pass anyway, so do that).
+
 	Responses have a method Next() that returns the next
 	emitted value and an error value. If the last element has been
 	received, the returned error value is io.EOF. If the
-	application code has sent an error using SetError, the error
-	ErrRcvdError is returned on next, indicating that the caller
-	should call Error(). Depending on the reponse type, other
-	errors may also occur.
+	application's code encounters a fatal error, it will call CloseWithError,
+	and that the error value will be returned via subsiquent calls to Next().
 
 	Pipes
 
+	TODO: ^ was this an actual type/interface or was this always an abstract metaphor?
+
 	Pipes are pairs (emitter, response), such that a value emitted
 	on the emitter can be received in the response value. Most
 	builtin emitters are "pipe" emitters. The most prominent

encoding.go

@@ -49,7 +49,10 @@ var Decoders = map[EncodingType]func(w io.Reader) Decoder{
 	},
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 type EncoderFunc func(req *Request) func(w io.Writer) Encoder
+
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 type EncoderMap map[EncodingType]EncoderFunc
 
 var Encoders = EncoderMap{
@@ -67,12 +70,14 @@ var Encoders = EncoderMap{
 	},
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func MakeEncoder(f func(*Request, io.Writer, interface{}) error) func(*Request) func(io.Writer) Encoder {
 	return func(req *Request) func(io.Writer) Encoder {
 		return func(w io.Writer) Encoder { return &genericEncoder{f: f, w: w, req: req} }
 	}
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func MakeTypedEncoder(f interface{}) func(*Request) func(io.Writer) Encoder {
 	val := reflect.ValueOf(f)
 	t := val.Type()

executor.go

@@ -4,6 +4,7 @@ import (
 	"context"
 )
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 type Executor interface {
 	Execute(req *Request, re ResponseEmitter, env Environment) error
 }
@@ -22,6 +23,7 @@ type MakeEnvironment func(context.Context, *Request) (Environment, error)
 // The user can define a function like this to pass it to cli.Run.
 type MakeExecutor func(*Request, interface{}) (Executor, error)
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func NewExecutor(root *Command) Executor {
 	return &executor{
 		root: root,

flushfwd.go

@@ -18,6 +18,7 @@ func (ff *flushfwder) Close() error {
 	return ff.ResponseEmitter.Close()
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func NewFlushForwarder(re ResponseEmitter, f Flusher) ResponseEmitter {
 	return &flushfwder{ResponseEmitter: re, Flusher: f}
 }

responseemitter.go

@@ -41,7 +41,6 @@ type ResponseEmitter interface {
 	CloseWithError(error) error
 
 	// SetLength sets the length of the output
-	// err is an interface{} so we don't have to manually convert to error.
 	SetLength(length uint64)
 
 	// Emit sends a value.
@@ -71,6 +70,7 @@ func Copy(re ResponseEmitter, res Response) error {
 	}
 }
 
+// TODO: no documentation; [54dbca2b-17f2-42a8-af93-c8d713866138]
 func EmitChan(re ResponseEmitter, ch <-chan interface{}) error {
 	for v := range ch {
 		err := re.Emit(v)