improve docs

doc.go

@@ -19,30 +19,54 @@
 	description of the arguments and options, the command's
 	processing function and a type to let the caller know what
 	type will be emitted. Optionally one of the functions PostRun
-	and Marshaler may be defined that consumes the function's
+	and Encoder may be defined that consumes the function's
 	emitted values and generates a visual representation for e.g.
-	the terminal. Marshaler works on a value-by-value basis, while
+	the terminal. Encoders work on a value-by-value basis, while
 	PostRun operates on the value stream.
 
 	Emitters
 
+
+
 	An emitter has the Emit method, that takes the command's
 	function's output as an argument and passes it to the user.
+
+		type ResponseEmitter interface {
+			io.Closer
+			SetLength(length uint64)
+			SetError(err interface{}, code cmdkit.ErrorType)
+			Emit(value interface{}) error
+		}
+
 	The command's function does not know what kind of emitter it
 	works with, so the same function may run locally or on a
-	server, using an rpc interface.
+	server, using an rpc interface. Emitters can also send errors
+	using the SetError method.
 
 	The user-facing emitter usually is the cli emitter. Values
 	emitter here will be printed to the terminal using either the
-	Marshaler or the PostRun function.
+	Encoders or the PostRun function.
 
 	Responses
 
+
 	A response is a value that the user can read emitted values
-	from. Responses have a method Next() that returns the next
+	from.
+
+		type Response interface {
+			Request() Request
+			Error() *cmdkit.Error
+			Length() uint64
+			Next() (interface{}, error)
+		}
+
+	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. Depending on the
-	reponse type, other errors may also occur.
+	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.
 
 	Pipes
 
@@ -64,5 +88,6 @@
 	To get a better idea of what's going on, take a look at the
 	examples at
 	https://github.com/ipfs/go-ipfs-cmds/tree/master/examples.
+
 */
 package cmds

examples/adder/cmd.go

@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"strconv"
 
-	"gx/ipfs/QmPMeikDc7tQEDvaS66j1bVPQ2jBkvFwz3Qom5eA5i4xip/go-ipfs-cmdkit"
+	"github.com/ipfs/go-ipfs-cmdkit"
 	"gx/ipfs/QmezbW7VUAiu3aSV6r4TdB9pwficnnbtWYKRsoEKF2w8G2/go-ipfs-cmds"
 )
 

examples/adder/remote/client/main.go

@@ -5,7 +5,7 @@ import (
 
 	"github.com/ipfs/go-ipfs-cmds/examples/adder"
 
-	cmdkit "gx/ipfs/QmPMeikDc7tQEDvaS66j1bVPQ2jBkvFwz3Qom5eA5i4xip/go-ipfs-cmdkit"
+	cmdkit "github.com/ipfs/go-ipfs-cmdkit"
 	cmds "gx/ipfs/QmezbW7VUAiu3aSV6r4TdB9pwficnnbtWYKRsoEKF2w8G2/go-ipfs-cmds"
 
 	cli "gx/ipfs/QmezbW7VUAiu3aSV6r4TdB9pwficnnbtWYKRsoEKF2w8G2/go-ipfs-cmds/cli"