From 6fd877deaace4e29a6a62022ee27beb428e48165 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:16:27 -0700 Subject: [PATCH] doc: Add some docs explaining the sub-package layout Based on [1]. [1]: https://github.com/ipfs/go-ipfs/issues/1158 --- doc.go | 27 ++++++++++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/doc.go b/doc.go index 4dadc4e6a..fdf2f6909 100644 --- a/doc.go +++ b/doc.go @@ -1,2 +1,27 @@ -// IPFS is a global, versioned, peer-to-peer filesystem +/* +IPFS is a global, versioned, peer-to-peer filesystem + +There are sub-packages within the ipfs package for various low-level +utilities, which are in turn assembled into: + +core/...: + The low-level API that gives consumers all the knobs they need, + which we try hard to keep stable. +shell/...: + The high-level API that gives consumers easy access to common + operations (e.g. create a file node from a reader without wrapping + with metadata). We work really hard to keep this stable. + +Then on top of the core/... and shell/... Go APIs, we have: + +cmd/...: + Command-line executables +test/...: + Integration tests, etc. + +To avoid cyclic imports, imports should never pull in higher-level +APIs into a lower-level package. For example, you could import all of +core and shell from cmd/... or test/..., but you couldn't import any +of shell from core/.... +*/ package ipfs