coreapi: add more docs for path

License: MIT
Signed-off-by: Łukasz Magiera <magik6k@gmail.com>

core/coreapi/interface/path.go

@@ -17,7 +17,9 @@ type Path interface {
 	// String returns the path as a string.
 	String() string
 
-	// Namespace returns the first component of the path
+	// Namespace returns the first component of the path.
+	//
+	// For example path "/ipfs/QmHash", calling Namespace() will return "ipfs"
 	Namespace() string
 
 	// Mutable returns false if the data pointed to by this path in guaranteed
@@ -29,13 +31,29 @@ type Path interface {
 
 // ResolvedPath is a resolved Path
 type ResolvedPath interface {
-	// Cid returns the CID referred to by path
+	// Cid returns the CID of the object referenced by the path.
+	//
+	// Example:
+	// If you have 3 linked objects: QmRoot -> A -> B, and resolve path
+	// "/ipfs/QmRoot/A/B", the Cid method will return the CID of object B
 	Cid() *cid.Cid
 
-	// Root returns the CID of root path
+	// Root returns the CID of the root object of the path
+	//
+	// Example:
+	// If you have 3 linked objects: QmRoot -> A -> B, and resolve path
+	// "/ipfs/QmRoot/A/B", the Root method will return the CID of object QmRoot
 	Root() *cid.Cid
 
 	// Remainder returns unresolved part of the path
+	//
+	// Example:
+	// If you have 2 linked objects: QmRoot -> A, where A is a CBOR node
+	// containing the following data:
+	//
+	// {"foo": {"bar": 42}}
+	//
+	// When resolving "/ipld/QmRoot/A/foo/bar", Remainder will return "foo/bar"
 	Remainder() string
 
 	Path