Merge pull request #1185 from wking/go-doc

Add package comments to packages that are missing them

blockservice/worker/bench/main.go

@@ -1,3 +1,12 @@
+/*
+Benchmark github.com/ipfs/go-ipfs/blockservice/worker.
+
+Loop over a range of workers and buffer sizes and measure the time it
+per block-transfer operation for each value.  Run with:
+
+  $ go run "${GOPATH}/src/github.com/ipfs/go-ipfs/blockservice/worker/bench/main.go"
+*/
+
 package main
 
 import (

commands/command.go

@@ -1,3 +1,11 @@
+/*
+Package commands provides an API for defining and parsing commands.
+
+Supporting nested commands, options, arguments, etc.  The commands
+package also supports a collection of marshallers for presenting
+output to the user, including text, JSON, and XML marshallers.
+*/
+
 package commands
 
 import (

core/commands/commands.go

@@ -1,3 +1,10 @@
+/*
+Package commands implements the IPFS command interface
+
+Using github.com/ipfs/go-ipfs/commands to define the command line and
+HTTP APIs.  This is the interface available to folks consuming IPFS
+from outside of the Go language.
+*/
 package commands
 
 import (

core/core.go

@@ -1,5 +1,12 @@
-// package core implements the IpfsNode object and methods for constructing
+/*
-// and properly setting it up.
+Package core implements the IpfsNode object and related methods.
+
+Packages underneath core/ provide a (relatively) stable, low-level API
+to carry out most IPFS-related tasks.  For more details on the other
+interfaces and how core/... fits into the bigger IPFS picture, see:
+
+  $ godoc github.com/ipfs/go-ipfs
+*/
 package core
 
 import (

core/corehttp/corehttp.go

@@ -1,3 +1,7 @@
+/*
+Package corehttp provides utilities for the webui, gateways, and other
+high-level HTTP interfaces to IPFS.
+*/
 package corehttp
 
 import (

core/corerepo/pinning.go

@@ -1,3 +1,16 @@
+/*
+Package corerepo provides pinning and garbage collection for local
+IPFS block services.
+
+IPFS nodes will keep local copies of any object that have either been
+added or requested locally.  Not all of these objects are worth
+preserving forever though, so the node adminstrator can pin objects
+they want to keep and unpin objects that they don't care about.
+
+Garbage collection sweeps iterate through the local block store
+removing objects that aren't pinned, which frees storage space for new
+objects.
+*/
 package corerepo
 
 import (

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