Merge pull request #286 from jbenet/docs

Add more documentation to ipfs

README.md

-# ipfs implementation in go. [![GoDoc](https://godoc.org/github.com/jbenet/go-ipfs?status.svg)](https://godoc.org/github.com/jbenet/go-ipfs) [![Build Status](https://travis-ci.org/jbenet/go-ipfs.svg?branch=master)](https://travis-ci.org/jbenet/go-ipfs)
+# ipfs implementation in go.
+[![GoDoc](https://godoc.org/github.com/jbenet/go-ipfs?status.svg)](https://godoc.org/github.com/jbenet/go-ipfs) [![Build Status](https://travis-ci.org/jbenet/go-ipfs.svg?branch=master)](https://travis-ci.org/jbenet/go-ipfs)
 
-See: https://github.com/jbenet/ipfs
+Ipfs is a global, versioned, peer-to-peer filesystem. It combines good ideas from
+Git, BitTorrent, Kademlia, SFS, and the Web. It is like a single bittorrent swarm,
+exchanging git objects. IPFS provides an interface as simple as the HTTP web, but
+with permanence built in. You can also mount the world at /ipfs.
+
+For more info see: https://github.com/jbenet/ipfs
 
 Please put all issues regarding IPFS _design_ in the
 [ipfs repo issues](https://github.com/jbenet/ipfs/issues).
@@ -18,13 +24,13 @@ go install
 
 NOTES:
 
-* `git` and mercurial (`hg`) are required in order for `go get` to fetch
+* `git` is required in order for `go get` to fetch
 all dependencies.
 * Package managers often contain out-of-date `golang` packages.
   Compilation from source is recommended.
 * If you are interested in development, please install the development
 dependencies as well.
-* **WARNING: older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting!**
+* *WARNING: older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting!*
   We strongly recommend you use the [latest version of OSX FUSE](http://osxfuse.github.io/).
   (See https://github.com/jbenet/go-ipfs/issues/177)
 
@@ -36,6 +42,7 @@ ipfs - global versioned p2p merkledag file system
 
 Basic commands:
 
+    init          Initialize ipfs local configuration.
     add <path>    Add an object to ipfs.
     cat <ref>     Show ipfs object data.
     ls <ref>      List links from an object.
@@ -44,6 +51,7 @@ Basic commands:
 Tool commands:
 
     config        Manage configuration.
+    update        Download and apply go-ipfs updates.
     version       Show ipfs version information.
     commands      List all available commands.
 
@@ -51,6 +59,13 @@ Advanced Commands:
 
     mount         Mount an ipfs read-only mountpoint.
     serve         Serve an interface to ipfs.
+    net-diag      Print network diagnostic
+
+Plumbing commands:
+
+    block         Interact with raw blocks in the datastore
+    object        Interact with raw dag nodes
+
 
 Use "ipfs help <command>" for more information about a command.
 ```
@@ -58,13 +73,30 @@ Use "ipfs help <command>" for more information about a command.
 ## Getting Started
 To start using ipfs, you must first initialize ipfs's config files on your
 system, this is done with `ipfs init`. See `ipfs help init` for information on
-arguments it takes. After initialization is complete, you can use `ipfs mount`,
-`ipfs add` and any of the other commands to explore!
+the optional arguments it takes. After initialization is complete, you can use
+`ipfs mount`, `ipfs add` and any of the other commands to explore!
+
+### Some things to try
+
+Basic proof of 'ipfs working' locally:
+
+	echo "hello world" > hello
+	ipfs add hello
+	# This should output a hash string that looks something like:
+	# QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o
+	ipfs cat <that hash>
+
 
+### Troubleshooting
+If you have previously installed ipfs before and you are running into
+problems getting a newer version to work, try deleting (or backing up somewhere
+else) your config directory (~/.go-ipfs by default) and rerunning `ipfs init`.
+This will reinitialize the config file to its defaults and clear out the local
+datastore of any bad entries.
 
-NOTE: if you have previously installed ipfs before and you are running into
-problems getting it to work, try deleting (or backing up somewhere else) your
-config directory (~/.go-ipfs by default) and rerunning `ipfs init`.
+For any other problems, check the [issues list](http://github.com/jbenet/go-ipfs/issues)
+and if you dont see your problem there, either come talk to us on irc (freenode #ipfs) or
+file an issue of your own!
 
 
 ## Contributing

blocks/blocks.go

+// package blocks contains the lowest level of ipfs data structures,
+// the raw block with a checksum.
 package blocks
 
 import (

blocks/bloom/filter.go

+// package bloom implements a simple bloom filter.
 package bloom
 
 import (

blocks/set/set.go

+// package set contains various different types of 'BlockSet's
 package set
 
 import (
@@ -7,6 +8,7 @@ import (
 
 var log = util.Logger("blockset")
 
+// BlockSet represents a mutable set of keyed blocks
 type BlockSet interface {
 	AddBlock(util.Key)
 	RemoveBlock(util.Key)

blockservice/blockservice.go

+// package blockservice implements a BlockService interface that provides
+// a single GetBlock/AddBlock interface that seamlessly retrieves data either
+// locally or from a remote peer through the exchange.
 package blockservice
 
 import (

blockstore/blockstore.go

+// package blockstore implements a thin wrapper over a datastore, giving a
+// clean interface for Getting and Putting block objects.
 package blockstore
 
 import (

config/config.go

+// package config implements the ipfs config file datastructures and utilities.
 package config
 
 import (

crypto/key.go

+// package crypto implements various cryptographic utilities used by ipfs.
+// This includes a Public and Private key interface and an RSA key implementation
+// that satisfies it.
 package crypto
 
 import (

crypto/spipe/handshake.go

-// Package spipe handles establishing secure communication between two peers.
-
+// package spipe handles establishing secure communication between two peers.
 package spipe
 
 import (

diagnostics/diag.go

+// package diagnostics implements a network diagnostics service that
+// allows a request to traverse the network and gather information
+// on every node connected to it.
 package diagnostics
 
 import (

exchange/bitswap/bitswap.go

+// package bitswap implements the IPFS Exchange interface with the BitSwap
+// bilateral exchange protocol.
 package bitswap
 
 import (

exchange/interface.go

+// package exchange defines the IPFS Exchange interface
 package exchange
 
 import (

exchange/offline/offline.go

-package bitswap
+// package offline implements an object that implements the exchange
+// interface but returns nil values to every request.
+package offline
 
 import (
 	"errors"

exchange/offline/offline_test.go

-package bitswap
+package offline
 
 import (
 	"testing"

fuse/ipns/ipns_unix.go

+// package fuse/ipns implements a fuse filesystem that interfaces
+// with ipns, the naming system for ipfs.
 package ipns
 
 import (

fuse/readonly/readonly_unix.go

-// A Go mirror of libfuse's hello.c
-
 // +build linux darwin freebsd
 
+// package fuse/readonly implements a fuse filesystem to access files
+// stored inside of ipfs.
 package readonly
 
 import (

importer/chunk/splitting.go

+// package chunk implements streaming block splitters
 package chunk
 
 import (

importer/importer.go

+// package importer implements utilities used to create ipfs DAGs from files
+// and readers
 package importer
 
 import (

merkledag/merkledag.go

+// package merkledag implements the ipfs Merkle DAG datastructures.
 package merkledag
 
 import (

net/conn/interface.go

@@ -22,7 +22,7 @@ type Conn interface {
 	// LocalMultiaddr is the Multiaddr on this side
 	LocalMultiaddr() ma.Multiaddr
 
-	// LocalPeer is the Peer on this side
+	// LocalPeer is the Peer on our side of the connection
 	LocalPeer() peer.Peer
 
 	// RemoteMultiaddr is the Multiaddr on the remote side
@@ -37,10 +37,9 @@ type Conn interface {
 	// Out returns a writable message channel
 	Out() chan<- []byte
 
+	// Get an error from this conn if one is available
+	// TODO: implement a better error handling system
 	GetError() error
-
-	// Close ends the connection
-	// Close() error  -- already in ContextCloser
 }
 
 // Dialer is an object that can open connections. We could have a "convenience"

net/handshake/doc.go

+/*
+package handshake implements the ipfs handshake protocol
+
+IPFS Handshake
+
+The IPFS Protocol Handshake is divided into three sequential steps
+
+1. Version Handshake (`Hanshake1`)
+
+2. Secure Channel (`NewSecureConn`)
+
+3. Services (`Handshake3`)
+
+Currently these parts currently happen sequentially (costing an awful 5 RTT),
+but can be optimized to 2 RTT.
+
+Version Handshake
+
+The Version Handshake ensures that nodes speaking to each other can interoperate.
+They send each other protocol versions and ensure there is a match on the major
+version (semver).
+
+Secure Channel
+
+The second part exchanges keys and establishes a secure comm channel. This
+follows ECDHE TLS, but *isn't* TLS. (why will be written up elsewhere).
+
+Services
+
+The Services portion sends any additional information on nodes needed
+by the nodes, e.g. Listen Address (the received address could be a Dial addr),
+and later on can include Service listing (dht, exchange, ipns, etc).
+*/
+package handshake

net/interface.go

@@ -59,9 +59,9 @@ type Handler srv.Handler
 // Service interface for network resources.
 type Service srv.Service
 
-// Dialer service that can dial to peers
+// Dialer represents a service that can dial out to peers
 // (this is usually just a Network, but other services may not need the whole
-// thing, and thus it becomes easier to mock)
+// stack, and thus it becomes easier to mock)
 type Dialer interface {
 
 	// DialPeer attempts to establish a connection to a given peer

net/mux/mux.go

+// package mux implements a protocol muxer.
 package mux
 
 import (

net/net.go

+// package net provides an interface for ipfs to interact with the network through
 package net
 
 import (

net/swarm/swarm.go

+// package swarm implements a connection muxer with a pair of channels
+// to synchronize all network communication.
 package swarm
 
 import (

path/path.go

+// package path implements utilities for resolving paths within ipfs.
 package path
 
 import (

peer/peer.go

+// package peer implements an object used to represent peers in the ipfs network.
 package peer
 
 import (

pin/pin.go

+// package pin implemnts structures and methods to keep track of
+// which objects a user wants to keep stored locally.
 package pin
 
 import (

routing/dht/dht.go

+// package dht implements a distributed hash table that satisfies the ipfs routing
+// interface. This DHT is modeled after kademlia with Coral and S/Kademlia modifications.
 package dht
 
 import (

routing/dht/handlers.go

@@ -12,6 +12,7 @@ import (
 	ds "github.com/jbenet/go-ipfs/Godeps/_workspace/src/github.com/jbenet/go-datastore"
 )
 
+// The number of closer peers to send on requests.
 var CloserPeerCount = 4
 
 // dhthandler specifies the signature of functions that handle DHT messages.

routing/dht/util.go

@@ -9,10 +9,10 @@ import (
 // Pool size is the number of nodes used for group find/set RPC calls
 var PoolSize = 6
 
-// We put the 'K' in kademlia!
+// K is the maximum number of requests to perform before returning failure.
 var KValue = 10
 
-// Its in the paper, i swear
+// Alpha is the concurrency factor for asynchronous requests.
 var AlphaValue = 3
 
 // A counter for incrementing a variable across multiple threads

routing/kbucket/bucket.go

-package dht
+package kbucket
 
 import (
 	"container/list"

routing/kbucket/table.go

-package dht
+// package kbucket implements a kademlia 'k-bucket' routing table.
+package kbucket
 
 import (
 	"container/list"

routing/kbucket/table_test.go

-package dht
+package kbucket
 
 import (
 	crand "crypto/rand"

routing/kbucket/util.go

-package dht
+package kbucket
 
 import (
 	"bytes"

routing/routing.go

+// package routing defines the interface for a routing system used by ipfs.
 package routing
 
 import (

server/http/http.go

+// package http implements an http server that serves static content from ipfs
 package http
 
 import (

unixfs/io/doc.go

+// package unixfs/io implements convenience objects for working with the ipfs
+// unixfs data format.
+package io

util/util.go

+// package util implements various utility functions used within ipfs
+// that do not currently have a better place to live.
 package util
 
 import (