Update documentation

- Remove `encode_doc.go`
- Add `README.md` with Codec section
- Update comments for `Encode` and `Decode` methods
- Add `node` package comment

Author: qdm12

internal/trie/node/README.md

@@ -0,0 +1,31 @@
+# Trie node
+
+Package node defines the `Node` structure with methods to be used in the modified Merkle-Patricia Radix-16 trie.
+
+## Codec
+
+The following sub-sections precise the encoding of a node.
+This encoding is formally described in [the Polkadot specification](https://spec.polkadot.network/#sect-state-storage).
+
+### Header
+
+Each node encoding has a header of one or more bytes.
+The first byte contains the node variant and some or all of the partial key length of the node.
+If the partial key length cannot fit in the first byte, additional bytes are added to the header to represent the total partial key length.
+
+### Partial key
+
+The header is then concatenated with the partial key of the node, encoded as Little Endian bytes.
+
+### Remaining bytes
+
+The remaining bytes appended depend on the node variant.
+
+- For leaves, the SCALE-encoded leaf value is appended.
+- For branches, the following elements are concatenated in this order and appended to the previous header+partial key:
+  - Children bitmap (2 bytes)
+  - SCALE-encoded node value
+  - Hash(Encoding(Child[0]))
+  - Hash(Encoding(Child[1]))
+  - ...
+  - Hash(Encoding(Child[15]))

internal/trie/node/decode.go

@@ -19,6 +19,9 @@ var (
 )
 
 // Decode decodes a node from a reader.
+// The encoding format is documented in the README.md
+// of this package, and specified in the Polkadot spec at
+// https://spec.polkadot.network/#sect-state-storage
 // For branch decoding, see the comments on decodeBranch.
 // For leaf decoding, see the comments on decodeLeaf.
 func Decode(reader io.Reader) (n *Node, err error) {
@@ -47,7 +50,7 @@ func Decode(reader io.Reader) (n *Node, err error) {
 	}
 }
 
-// decodeBranch reads and decodes from a reader with the encoding specified in internal/trie/node/encode_doc.go.
+// decodeBranch reads from a reader and decodes to a node branch.
 // Note that since the encoded branch stores the hash of the children nodes, we are not
 // reconstructing the child nodes from the encoding. This function instead stubs where the
 // children are known to be with an empty leaf. The children nodes hashes are then used to
@@ -115,7 +118,7 @@ func decodeBranch(reader io.Reader, variant byte, partialKeyLength uint16) (
 	return node, nil
 }
 
-// decodeLeaf reads and decodes from a reader with the encoding specified in lib/trie/node/encode_doc.go.
+// decodeLeaf reads from a reader and decodes to a leaf node.
 func decodeLeaf(reader io.Reader, partialKeyLength uint16) (node *Node, err error) {
 	node = &Node{
 		Dirty: true,

internal/trie/node/encode.go

@@ -12,7 +12,9 @@ import (
 )
 
 // Encode encodes the node to the buffer given.
-// The encoding format is documented in encode_doc.go.
+// The encoding format is documented in the README.md
+// of this package, and specified in the Polkadot spec at
+// https://spec.polkadot.network/#sect-state-storage
 func (n *Node) Encode(buffer Buffer) (err error) {
 	if !n.Dirty && n.Encoding != nil {
 		_, err = buffer.Write(n.Encoding)

internal/trie/node/encode_doc.go

@@ -1,6 +1,8 @@
 // Copyright 2021 ChainSafe Systems (ON)
 // SPDX-License-Identifier: LGPL-3.0-only
 
+// Package node defines the `Node` structure with methods
+// to be used in the modified Merkle-Patricia Radix-16 trie.
 package node
 
 import (