doc: Add some docs explaining the sub-package layout
Based on [1]. [1]: https://github.com/ipfs/go-ipfs/issues/1158
W. Trevor King committed
May 2, 2015 at 08:16 UTC
6fd877deaace4e29a6a62022ee27beb428e48165
1 file changed
+26
-1
doc.go
+26
-1
@@ -1,2 +1,27 @@
1
-// IPFS is a global, versioned, peer-to-peer filesystem
1
+/*
2
+IPFS is a global, versioned, peer-to-peer filesystem
3
+
4
+There are sub-packages within the ipfs package for various low-level
5
+utilities, which are in turn assembled into:
6
+
7
+core/...:
8
+ The low-level API that gives consumers all the knobs they need,
9
+ which we try hard to keep stable.
10
+shell/...:
11
+ The high-level API that gives consumers easy access to common
12
+ operations (e.g. create a file node from a reader without wrapping
13
+ with metadata). We work really hard to keep this stable.
14
+
15
+Then on top of the core/... and shell/... Go APIs, we have:
16
+
17
+cmd/...:
18
+ Command-line executables
19
+test/...:
20
+ Integration tests, etc.
21
+
22
+To avoid cyclic imports, imports should never pull in higher-level
23
+APIs into a lower-level package. For example, you could import all of
24
+core and shell from cmd/... or test/..., but you couldn't import any
25
+of shell from core/....
26
+*/
27
package ipfs