coreapi: more docs for ResolvedPath
License: MIT Signed-off-by: Łukasz Magiera <magik6k@gmail.com>
Łukasz Magiera committed
Jun 12, 2018 at 02:57 UTC
082498de6d779fdbddb70109cea8373ef1d4cfb5
1 file changed
+35
-6
core/coreapi/interface/path.go
+35
-6
@@ -29,13 +29,38 @@ type Path interface {
29
Mutable() bool
30
}
31
32
-// ResolvedPath is a resolved Path
32
+// ResolvedPath is a path which was resolved to the last resolvable node
33
type ResolvedPath interface {
34
- // Cid returns the CID of the object referenced by the path.
34
+ // Cid returns the CID of the node referenced by the path. Remainder of the
35
+ // path is guaranteed to be within the node.
36
//
36
- // Example:
37
- // If you have 3 linked objects: QmRoot -> A -> B, and resolve path
38
- // "/ipfs/QmRoot/A/B", the Cid method will return the CID of object B
37
+ // Examples:
38
+ // If you have 3 linked objects: QmRoot -> A -> B:
39
+ //
40
+ // cidB := {"foo": {"bar": 42 }}
41
+ // cidA := {"B": {"/": cidB }}
42
+ // cidRoot := {"A": {"/": cidA }}
43
+ //
44
+ // And resolve paths:
45
+ // * "/ipfs/${cidRoot}"
46
+ // * Calling Cid() will return `cidRoot`
47
+ // * Calling Root() will return `cidRoot`
48
+ // * Calling Remainder() will return ``
49
+ //
50
+ // * "/ipfs/${cidRoot}/A"
51
+ // * Calling Cid() will return `cidA`
52
+ // * Calling Root() will return `cidRoot`
53
+ // * Calling Remainder() will return ``
54
+ //
55
+ // * "/ipfs/${cidRoot}/A/B/foo"
56
+ // * Calling Cid() will return `cidB`
57
+ // * Calling Root() will return `cidRoot`
58
+ // * Calling Remainder() will return `foo`
59
+ //
60
+ // * "/ipfs/${cidRoot}/A/B/foo/bar"
61
+ // * Calling Cid() will return `cidB`
62
+ // * Calling Root() will return `cidRoot`
63
+ // * Calling Remainder() will return `foo/bar`
64
Cid() *cid.Cid
65
66
// Root returns the CID of the root object of the path
@@ -43,6 +68,8 @@ type ResolvedPath interface {
68
// Example:
69
// If you have 3 linked objects: QmRoot -> A -> B, and resolve path
70
// "/ipfs/QmRoot/A/B", the Root method will return the CID of object QmRoot
71
+ //
72
+ // For more examples see the documentation of Cid() method
73
Root() *cid.Cid
74
75
// Remainder returns unresolved part of the path
@@ -51,9 +78,11 @@ type ResolvedPath interface {
78
// If you have 2 linked objects: QmRoot -> A, where A is a CBOR node
79
// containing the following data:
80
//
54
- // {"foo": {"bar": 42}}
81
+ // {"foo": {"bar": 42 }}
82
//
83
// When resolving "/ipld/QmRoot/A/foo/bar", Remainder will return "foo/bar"
84
+ //
85
+ // For more examples see the documentation of Cid() method
86
Remainder() string
87
88
Path