From 9f2f29a9a42f9c7cdb1d39ccbed644efeb10ca31 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 30 Apr 2015 21:25:55 -0700 Subject: [PATCH 1/8] commands/command: Add a package comment I'm not quite sure which file in this package is the most prominent, but command.go seemed like a reasonable choice. --- commands/command.go | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/commands/command.go b/commands/command.go index f819b0440..e9774b85b 100644 --- a/commands/command.go +++ b/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 ( From beb3bab2054c8d6119bf2d7df4feeb26beb20e5b Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 30 Apr 2015 21:33:43 -0700 Subject: [PATCH 2/8] blockservice/worker/bench/main: Add a package comment --- blockservice/worker/bench/main.go | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/blockservice/worker/bench/main.go b/blockservice/worker/bench/main.go index 82c3dee13..c23770f78 100644 --- a/blockservice/worker/bench/main.go +++ b/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 ( From d2a28300a29f458534afe7c08915d09b574c99f8 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 30 Apr 2015 21:57:46 -0700 Subject: [PATCH 3/8] core/core: Explain that subpackages are our low-level API Discussion in [1]. [1]: https://github.com/ipfs/go-ipfs/issues/1158 --- core/core.go | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/core/core.go b/core/core.go index 40d5cbb70..e83da8e9e 100644 --- a/core/core.go +++ b/core/core.go @@ -1,5 +1,9 @@ -// 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. +*/ package core import ( From 6fd877deaace4e29a6a62022ee27beb428e48165 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:16:27 -0700 Subject: [PATCH 4/8] 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 From 81572ec236fdfe38729e4e4734c91ea90f060bcf Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:17:13 -0700 Subject: [PATCH 5/8] core/core: Refer back to the main go-ipfs docs So folks looking in core can figure out how it fits into the repository as a whole. --- core/core.go | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/core/core.go b/core/core.go index e83da8e9e..877ffe9c0 100644 --- a/core/core.go +++ b/core/core.go @@ -2,7 +2,10 @@ 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. +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 From 95ccdca9ec35db370653c48044ce18490759159e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:21:47 -0700 Subject: [PATCH 6/8] core/commands/commands: Add a package comment --- core/commands/commands.go | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/core/commands/commands.go b/core/commands/commands.go index 8b7080493..1d65cdbad 100644 --- a/core/commands/commands.go +++ b/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 ( From e02fc1ec6b351bae94df63ffc8280d9319abc0ca Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:35:34 -0700 Subject: [PATCH 7/8] core/corehttp/corehttp: Add a package comment I'm not entirely clear on the role that this package is filling, but this description seems like a reasonable guess based on a quick skim through it's exported API. --- core/corehttp/corehttp.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/core/corehttp/corehttp.go b/core/corehttp/corehttp.go index ff9bac704..e8852baaf 100644 --- a/core/corehttp/corehttp.go +++ b/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 ( From efa4907565e2110c3203ec0986d43dcb6bed323d Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 2 May 2015 08:55:43 -0700 Subject: [PATCH 8/8] core/corerepo/pinning: Add a package comment Currently garbage collection is triggered manually and there are no age-restrictions on the removal. I expect we'll eventually follow Git and auto-launch garbage collection when we hit some threshold of disk consumption (gc.auto). I expect we'll also follow Git and keep unpinned or unreachable objects (gc.pruneexpire, etc.). But we don't seem to do either of those yet. --- core/corerepo/pinning.go | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/core/corerepo/pinning.go b/core/corerepo/pinning.go index 81acba43e..cf2762713 100644 --- a/core/corerepo/pinning.go +++ b/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 (