From 7481749b5677aafb41f065240e684e9dd04b6e51 Mon Sep 17 00:00:00 2001
From: Rod Vagg <rod@vagg.org>
Date: Fri, 30 Sep 2022 13:37:13 +1000
Subject: [PATCH] doc: document potential panics and how to avoid them

---
 node.go | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/node.go b/node.go
index b2f93de..1b2bbaf 100644
--- a/node.go
+++ b/node.go
@@ -258,6 +258,11 @@ func (n *ProtoNode) Copy() format.Node {
 	return nnode
 }
 
+// RawNode returns the encoded byte form of this node.
+//
+// Note that this method can panic if a new encode is required and there is an
+// error performing the encode. To avoid a panic, use node.EncodeProtobuf(false)
+// instead (or prior to calling RawData) and check for its returned error value.
 func (n *ProtoNode) RawData() []byte {
 	out, err := n.EncodeProtobuf(false)
 	if err != nil {
@@ -392,21 +397,35 @@ func (n *ProtoNode) MarshalJSON() ([]byte, error) {
 
 // Cid returns the node's Cid, calculated according to its prefix
 // and raw data contents.
+//
+// Note that this method can panic if a new encode is required and there is an
+// error performing the encode. To avoid a panic, call
+// node.EncodeProtobuf(false) prior to calling Cid and check for its returned
+// error value.
 func (n *ProtoNode) Cid() cid.Cid {
 	// re-encode if necessary and we'll get a new cached CID
 	if _, err := n.EncodeProtobuf(false); err != nil {
 		panic(err)
 	}
-
 	return n.cached
 }
 
 // String prints the node's Cid.
+//
+// Note that this method can panic if a new encode is required and there is an
+// error performing the encode. To avoid a panic, call
+// node.EncodeProtobuf(false) prior to calling String and check for its returned
+// error value.
 func (n *ProtoNode) String() string {
 	return n.Cid().String()
 }
 
 // Multihash hashes the encoded data of this node.
+//
+// Note that this method can panic if a new encode is required and there is an
+// error performing the encode. To avoid a panic, call
+// node.EncodeProtobuf(false) prior to calling Multihash and check for its
+// returned error value.
 func (n *ProtoNode) Multihash() mh.Multihash {
 	return n.Cid().Hash()
 }