doc: more Node docs.

Signed-off-by: Eric Myhre <hash@exultant.us>

doc/dev.md

 Developer Docs
 ==============
 
-Code Layout
------------
-
-### Core / Data Model packages
-
-- `go-ipld-prime` -- the core interfaces are defined here.
-	- `ipld.Node` -- see the section on Nodes above; this is *the* interface.
-	- `ipld.ReprKind` -- this enumeration describes all the major kinds at the Data Model layer.
-- `go-ipld-prime/fluent` -- a user-facing helper package.
-	- `fluent.Node` -- does *not* implement `ipld.Node` for once; its methods don't return errors, but carry them until checked instead.
-- `go-ipld-prime/impl/free` -- one of the implementations of `ipld.Node`.
-	- `ipldfree.Node` -- internally uses go wildcard types to store all data.  Not itself hashable.
-- `go-ipld-prime/impl/cbor` -- one of the implementations of `ipld.Node`.
-	- `ipldcbor.Node` -- stores data as a skiplist over cbor-formatted byte slices.  Hashable!
-- `go-ipld-prime/impl/bind` -- one of the implementations of `ipld.Node`.
-	- `ipldbind.Node` -- uses `refmt` to map data onto user-provided Go types.  Not itself hashable.
-
-Node trees can be heterogeneous of their implementation types.
-For a complex example:
-one should be able to deserialize some data into an `ipldcbor.Node`;
-replace *some* substructure of the tree with `ipldfree.Node` datum;
-and convert the whole tree back to `ipldcbor.Node` to serialize out again.
-In doing so, we might expect that all of the data which started in a CBOR-backed
-node and was never replaced with new data would actually be carried by reference
-into the final tree, and as a result, re-serialization is the simple act of
-writing the bytes back out again as they came.
-
 ### Schema system packages
 
 // Note: this is somewhat more aspirational as yet.

doc/nodes.md

@@ -13,17 +13,72 @@ Nodes are trees.  It is not permissible to make a cycle of Node references.
 (Go programmers already familiar with the standard library `reflect` package
 may find it useful to think of `ipld.Node` as similar to `reflect.Value`.)
 
+Overview of Important Types
+---------------------------
+
+- `ipld.Node` -- see the section on Nodes above; this is *the* interface.
+- `ipld.NodeBuilder` -- an interface for building new Nodes.
+- `ipld.ReprKind` -- this enumeration describes all the major kinds at the Data Model layer.
+- `fluent.Node` -- similar to `ipld.Node`, but methods don't return errors, instead
+  carrying them until actually checked and/or using panics, making them easy to compose
+  in long expressions.
+
 
 the Node interface
 ------------------
 
-TODO
+Node is an interface for inspecting single values in IPLD.
+It has methods for
+extracting go primitive values for all the scalar node kinds,
+'traverse' methods for maps and lists which return further nodes,
+and iterator methods for maps.
+
+Node exposes only reader methods -- A Node is immutable.
+
+### kinds
+
+The `Node.Kind()` method returns an `ipld.ReprKind` enum value describing what
+kind of data this node contains in terms of the IPLD Data Model.
+
+The validity of many other methods can be anticipated by switching on the kind:
+for example, `AsString` is definitely going to error if `Kind() == ipld.ReprKind_Map`,
+and `TraverseField` is definitely going to error if `Kind() == ipld.ReprKind_String`.
 
 
 Node implementations
 --------------------
 
-TODO
+Since `Node` is an interface, it can have many implementations.
+We use different implementations to satisfy different performance objectives.
+There are several implementations in the core library, and users can bring their own.
+
+In go-ipld-prime, we have several implementations:
+
+- `impl/free` (imports as `ipldfree`) -- a generic unspecialized implementation
+  of `Node` which can contain any kind of content, internally using Go wildcard types.
+- `impl/bind` (imports as `ipldbind`) -- an implementation of `Node` which uses
+  reflection to bind to existing Go native objects and present them as nodes.
+- `impl/cbor` (imports as `ipldcbor`) -- an implementation of `Node` which stores
+  all content as cbor-encoded bytes -- interesting primarily because when doing
+  a bulk parse of cbor data, this can effectively defer parsing of values until
+  they're actually inspected, sometimes enabling considerable processing saving.
+- `typed` -- Typed nodes add a few more features onto the base Node interface
+  and add additional logical constraints to their contents -- more on this later.
+
+Different Node implementations can be mixed freely!
+
+For example: we can use `ipldcbor.Decode` to get an `ipldcbor.Node`
+(which internally is a sort of skip-list over the original CBOR byte slices),
+use `traverse.Transform` to replace just *some* nodes internally with new data
+we build out of an `ipldfree.NodeBuilder`, and then use `ipldcbor.Encode` again
+to emit the updated CBOR.  In this case, we are both able to use whatever kind
+of Node we want for our new data, and since we're keeping the rest of the tree
+in an `ipldcbor.Node` form we were able to skip all parsing of parts of the tree
+we aren't interested in, and when emitting bytes again we can recycle all the
+byte slices from the very first read -- in other words, zero copy operation
+(except for specifically the parts we've updated).  This is pretty neat!
+
+> Note: 'cbor' and 'bind' nodes are not yet fully supported.
 
 
 using NodeBuilder