core/commands2: Added descriptions for all the existing commands

core/commands2/bootstrap.go

@@ -10,26 +10,19 @@ import (
 
 	cmds "github.com/jbenet/go-ipfs/commands"
 	config "github.com/jbenet/go-ipfs/config"
-	//peer "github.com/jbenet/go-ipfs/peer"
-	//u "github.com/jbenet/go-ipfs/util"
 )
 
 type BootstrapOutput struct {
 	Peers []*config.BootstrapPeer
 }
 
+var peerOptionDesc = "A peer to add to the bootstrap list (in the format '<multiaddr>/<peerID>')"
+
 var bootstrapCmd = &cmds.Command{
-	Help: `ipfs bootstrap - show, or manipulate bootstrap node addresses
+	Description: "Show or edit the list of bootstrap peers",
-
+	Help: `Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'.
-Running 'ipfs bootstrap' with no arguments will run 'ipfs bootstrap list'.
-
-Commands:
-
-  list               Show the boostrap list.
-  add <address>      Add a node's address to the bootstrap list.
-  remove <address>   Remove an address from the bootstrap list.
-
 ` + bootstrapSecurityWarning,
+
 	Run:         bootstrapListCmd.Run,
 	Marshallers: bootstrapListCmd.Marshallers,
 	Subcommands: map[string]*cmds.Command{
@@ -40,11 +33,14 @@ Commands:
 }
 
 var bootstrapAddCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Add peers to the bootstrap list",
-		cmds.Argument{"peer", cmds.ArgString, true, true},
+	Help: `Outputs a list of peers that were added (that weren't already
-	},
+in the bootstrap list).
-	Help: `ipfs bootstrap add - add addresses to the bootstrap list
 ` + bootstrapSecurityWarning,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"peer", cmds.ArgString, true, true, peerOptionDesc},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		input, err := bootstrapInputToPeers(req.Arguments())
 		if err != nil {
@@ -81,11 +77,13 @@ var bootstrapAddCmd = &cmds.Command{
 }
 
 var bootstrapRemoveCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Removes peers from the bootstrap list",
-		cmds.Argument{"peer", cmds.ArgString, true, true},
+	Help: `Outputs the list of peers that were removed.
-	},
-	Help: `ipfs bootstrap remove - remove addresses from the bootstrap list
 ` + bootstrapSecurityWarning,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"peer", cmds.ArgString, true, true, peerOptionDesc},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		input, err := bootstrapInputToPeers(req.Arguments())
 		if err != nil {
@@ -122,7 +120,10 @@ var bootstrapRemoveCmd = &cmds.Command{
 }
 
 var bootstrapListCmd = &cmds.Command{
-	Help: "ipfs bootstrap list - Show addresses in the bootstrap list",
+	Description: "Lists peers in the bootstrap list",
+	Help: `Peers are output in the format '<multiaddr>/<peerID>'.
+`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		peers := req.Context().Config.Bootstrap
 		res.SetOutput(&BootstrapOutput{peers})

core/commands2/cat.go

@@ -10,14 +10,15 @@ import (
 )
 
 var catCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Show IPFS object data",
-		cmds.Argument{"object", cmds.ArgString, true, true},
+	Help: `Retrieves the object named by <ipfs-path> and outputs the data
-	},
-	Help: `ipfs cat <object> - Show ipfs object data.
-
-	Retrieves the object named by <object> and outputs the data
 	it contains.
 	`,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"ipfs-path", cmds.ArgString, true, true,
+			"The path to the IPFS object(s) to be outputted"},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		node := req.Context().Node
 		readers := make([]io.Reader, 0, len(req.Arguments()))

core/commands2/commands.go

@@ -13,12 +13,10 @@ type Command struct {
 }
 
 var commandsCmd = &cmds.Command{
-	// TODO UsageLine: "commands",
+	Description: "List all available commands.",
-	// TODO Short:     "List all available commands.",
+	Help: `Lists all available commands (and subcommands) and exits.
-	Help: `ipfs commands - List all available commands.
-
-    Lists all available commands (and sub-commands) and exits.
 `,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		root := outputCommand("ipfs", Root)
 		res.SetOutput(&root)

core/commands2/config.go

@@ -18,18 +18,8 @@ type ConfigField struct {
 }
 
 var configCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Get/set IPFS config values",
-		cmds.Argument{"key", cmds.ArgString, true, false},
+	Help: `Examples:
-		cmds.Argument{"value", cmds.ArgString, false, false},
-	},
-	Help: `ipfs config <key> [value] - Get/Set ipfs config values.
-
-    ipfs config <key>          - Get value of <key>
-    ipfs config <key> <value>  - Set value of <key> to <value>
-    ipfs config show           - Show config file
-    ipfs config edit           - Edit config file in $EDITOR
-
-Examples:
 
   Get the value of the 'datastore.path' key:
 
@@ -38,8 +28,14 @@ Examples:
   Set the value of the 'datastore.path' key:
 
       ipfs config datastore.path ~/.go-ipfs/datastore
-
 `,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"key", cmds.ArgString, true, false,
+			"The key of the config entry (e.g. \"Addresses.API\")"},
+		cmds.Argument{"value", cmds.ArgString, false, false,
+			"The value to set the config entry to"},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		args := req.Arguments()
 
@@ -110,6 +106,11 @@ Examples:
 }
 
 var configShowCmd = &cmds.Command{
+	Description: "Outputs the content of the config file",
+	Help: `WARNING: Your private key is stored in the config file, and it will be
+included in the output of this command.
+`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		filename, err := config.Filename(req.Context().ConfigRoot)
 		if err != nil {
@@ -128,6 +129,11 @@ var configShowCmd = &cmds.Command{
 }
 
 var configEditCmd = &cmds.Command{
+	Description: "Opens the config file for editing in $EDITOR",
+	Help: `To use 'ipfs config edit', you must have the $EDITOR environment
+variable set to your preferred text editor.
+`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		filename, err := config.Filename(req.Context().ConfigRoot)
 		if err != nil {

core/commands2/diag.go

@@ -28,24 +28,20 @@ type DiagnosticOutput struct {
 }
 
 var diagCmd = &cmds.Command{
-	Help: `ipfs diag - Generate diagnostic reports.
+	Description: "Generates diagnostic reports",
 
-    ipfs diag net                     - Generate a network diagnostic report.
-	`,
 	Subcommands: map[string]*cmds.Command{
 		"net": diagNetCmd,
 	},
 }
 
 var diagNetCmd = &cmds.Command{
-	// TODO UsageLine: "net-diag",
+	Description: "Generates a network diagnostics report",
-	// TODO Short:     "Generate a diagnostics report",
+	Help: `Sends out a message to each node in the network recursively
-	Help: `ipfs diag net - Generate a network diagnostics report.
-
-	Sends out a message to each node in the network recursively
 requesting a listing of data about them including number of
 connected peers and latencies between them.
 `,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node
 

core/commands2/log.go

@@ -8,19 +8,17 @@ import (
 )
 
 var logCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Change the logging level",
-		cmds.Argument{"subsystem", cmds.ArgString, true, false},
+	Help: `'ipfs log' is a utility command used to change the logging
-		cmds.Argument{"level", cmds.ArgString, true, false},
+output of a running daemon.
-	},
-	// TODO UsageLine: "log <name> <level> ",
-	// TODO Short:     "switch logging levels of a running daemon",
-	Help: `ipfs log <subsystem> <level> - switch logging levels of a running daemon
-
-   <subsystem> is a the subsystem logging identifier. Use * for all subsystems.
-   <level> is one of: debug, info, notice, warning, error, critical
-
-ipfs log is a utility command used to change the logging output of a running daemon.
 `,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"subsystem", cmds.ArgString, true, false,
+			"the subsystem logging identifier. Use * for all subsystems."},
+		cmds.Argument{"level", cmds.ArgString, true, false,
+			"one of: debug, info, notice, warning, error, critical"},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		args := req.Arguments()
 		if err := u.SetLogLevel(args[0].(string), args[1].(string)); err != nil {

core/commands2/ls.go

@@ -23,20 +23,15 @@ type LsOutput struct {
 }
 
 var lsCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "List links from an object.",
-		cmds.Argument{"object", cmds.ArgString, false, true},
+	Help: `Retrieves the object named by <ipfs-path> and displays the links
-	},
+it contains.
-	// TODO UsageLine: "ls",
-	// TODO Short:     "List links from an object.",
-	// TODO docs read ipfs-path. argument says option. which?
-	Help: `ipfs ls <ipfs-path> - List links from an object.
-
-    Retrieves the object named by <ipfs-path> and displays the links
-    it contains, with the following format:
-
-    <link base58 hash> <link size in bytes> <link name>
-
 `,
+
+	Arguments: []cmds.Argument{
+		cmds.Argument{"ipfs-path", cmds.ArgString, false, true,
+			"The path to the IPFS object(s) to list links from"},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		node := req.Context().Node
 

core/commands2/mount_unix.go

@@ -17,25 +17,24 @@ import (
 const mountTimeout = time.Second
 
 var mountCmd = &cmds.Command{
-	Arguments: []cmds.Argument{
+	Description: "Mounts IPFS to the filesystem (read-only)",
-		cmds.Argument{Name: "os-path", Type: cmds.ArgString, Required: false, Variadic: false},
+	Help: `Mount ipfs at a read-only mountpoint on the OS. All ipfs objects
-	},
+will be accessible under that directory. Note that the root will
+not be listable, as it is virtual. Accessing known paths directly.
+`,
+
 	Options: []cmds.Option{
 
 		// TODO text: specify a mountpoint for ipfs
 		// TODO longform
-		cmds.Option{[]string{"f"}, cmds.String},
+		cmds.Option{[]string{"f"}, cmds.String,
+			"The path where IPFS should be mounted (default is '/ipfs')"},
 
 		// TODO text: specify a mountpoint for ipns
 		// TODO longform
-		cmds.Option{[]string{"n"}, cmds.String},
+		cmds.Option{[]string{"n"}, cmds.String,
+			"The path where IPNS should be mounted (default is '/ipns')"},
 	},
-	Help: `ipfs mount <os-path> - Mount an ipfs read-only mountpoint.
-
-    Mount ipfs at a read-only mountpoint on the OS. All ipfs objects
-    will be accessible under that directory. Note that the root will
-    not be listable, as it is virtual. Accessing known paths directly.
-`,
 	Run: func(res cmds.Response, req cmds.Request) {
 		ctx := req.Context()
 

core/commands2/mount_windows.go

@@ -7,7 +7,9 @@ import (
 )
 
 var ipfsMount = &cmds.Command{
-	Help: `Not yet implemented on Windows.`,
+	Description: "Not yet implemented on Windows",
+	Help:        `Not yet implemented on Windows. :(`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		res.SetError(errors.New("Mount isn't compatible with Windows yet"), cmds.ErrNormal)
 	},

core/commands2/name.go

@@ -8,14 +8,8 @@ type IpnsEntry struct {
 }
 
 var nameCmd = &cmds.Command{
-	// TODO UsageLine: "name [publish | resolve]",
+	Description: "IPFS namespace (IPNS) tool",
-	// TODO Short:     "ipfs namespace (ipns) tool",
+	Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and
-	Help: `ipfs name - Get/Set ipfs config values.
-
-    ipfs name publish [<name>] <ref>  - Assign the <ref> to <name>
-    ipfs name resolve [<name>]        - Resolve the <ref> value of <name>
-
-IPNS is a PKI namespace, where names are the hashes of public keys, and
 the private key enables publishing new (signed) values. In both publish
 and resolve, the default value of <name> is your own identity public key.
 
@@ -37,12 +31,13 @@ Resolve the value of your identity:
   > ipfs name resolve
   QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
-Resolve te value of another name:
+Resolve the value of another name:
 
   > ipfs name resolve QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n
   QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
 `,
+
 	Subcommands: map[string]*cmds.Command{
 		"publish": publishCmd,
 		"resolve": resolveCmd,

core/commands2/pin.go

@@ -10,10 +10,8 @@ import (
 )
 
 var pinCmd = &cmds.Command{
-	// TODO UsageLine: "pin",
+	Description: "Keeps objects stored locally",
-	// TODO Short:     "",
+
-	Help: `ipfs pin [add|rm] - object pinning commands
-	`,
 	Subcommands: map[string]*cmds.Command{
 		"add": addPinCmd,
 		"rm":  rmPinCmd,
@@ -21,19 +19,18 @@ var pinCmd = &cmds.Command{
 }
 
 var addPinCmd = &cmds.Command{
-	// TODO UsageLine: "add",
+	Description: "Pins objects to local storage",
-	// TODO Short:     "pin an ipfs object to local storage.",
+	Help: `Keeps the object(s) named by <ipfs-path> in local storage. If the object
-	Help: `ipfs pin add <ipfs-path> - pin ipfs object to local storage.
+isn't already being stored, IPFS retrieves it.
-
-    Retrieves the object named by <ipfs-path> and stores it locally
-    on disk.
 `,
-	Options: []cmds.Option{
+
-		cmds.Option{[]string{"recursive", "r"}, cmds.Bool},
-		cmds.Option{[]string{"depth", "d"}, cmds.Uint},
-	},
 	Arguments: []cmds.Argument{
-		cmds.Argument{"object", cmds.ArgString, true, true},
+		cmds.Argument{"ipfs-path", cmds.ArgString, true, true,
+			"Path to object(s) to be pinned"},
+	},
+	Options: []cmds.Option{
+		cmds.Option{[]string{"recursive", "r"}, cmds.Bool,
+			"Recursively pin the object linked to by the specified object(s)"},
 	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node
@@ -58,18 +55,18 @@ var addPinCmd = &cmds.Command{
 }
 
 var rmPinCmd = &cmds.Command{
-	// TODO UsageLine: "rm",
+	Description: "Unpin an object from local storage",
-	// TODO Short:     "unpin an ipfs object from local storage.",
+	Help: `Removes the pin from the given object allowing it to be garbage
-	Help: `ipfs pin rm <ipfs-path> - unpin ipfs object from local storage.
-
-	Removes the pin from the given object allowing it to be garbage
 	collected if needed.
 `,
-	Options: []cmds.Option{
+
-		cmds.Option{[]string{"recursive", "r"}, cmds.Bool},
-	},
 	Arguments: []cmds.Argument{
-		cmds.Argument{"object", cmds.ArgString, true, true},
+		cmds.Argument{"ipfs-path", cmds.ArgString, true, true,
+			"Path to object(s) to be unpinned"},
+	},
+	Options: []cmds.Option{
+		cmds.Option{[]string{"recursive", "r"}, cmds.Bool,
+			"Recursively unpin the object linked to by the specified object(s)"},
 	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node

core/commands2/publish.go

@@ -14,13 +14,9 @@ import (
 var errNotOnline = errors.New("This command must be run in online mode. Try running 'ipfs daemon' first.")
 
 var publishCmd = &cmds.Command{
-	// TODO UsageLine: "publish",
+	Description: "Publish an object to IPNS",
-	// TODO Short:     "publish a <ref> to ipns.",
+	Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and
-	Help: `ipfs name publish [<name>] <ref> - publish a <ref> to ipns.
+the private key enables publishing new (signed) values.
-
-IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In publish, the
-default value of <name> is your own identity public key.
 
 Examples:
 
@@ -35,9 +31,12 @@ Publish a <ref> to another public key:
   published name QmbCMUZw6JFeZ7Wp9jkzbye3Fzp2GGcPgC3nmeUjfVF87n to QmatmE9msSfkKxoffpHwNLNKgwZG8eT9Bud6YoPab52vpy
 
 `,
+
 	Arguments: []cmds.Argument{
-		cmds.Argument{"name", cmds.ArgString, false, false},
+		cmds.Argument{"name", cmds.ArgString, false, false,
-		cmds.Argument{"object", cmds.ArgString, true, false},
+			"The IPNS name to publish to. Defaults to your node's peerID"},
+		cmds.Argument{"ipfs-path", cmds.ArgString, true, false,
+			"IPFS path of the obejct to be published at <name>"},
 	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node

core/commands2/resolve.go

@@ -12,13 +12,9 @@ type ResolveOutput struct {
 }
 
 var resolveCmd = &cmds.Command{
-	// TODO UsageLine: "resolve",
+	Description: "Gets the value currently published at an IPNS name",
-	// TODO Short:     "resolve an ipns name to a <ref>",
+	Help: `IPNS is a PKI namespace, where names are the hashes of public keys, and
-	Help: `ipfs name resolve [<name>] - Resolve an ipns name to a <ref>.
+the private key enables publishing new (signed) values.
-
-IPNS is a PKI namespace, where names are the hashes of public keys, and
-the private key enables publishing new (signed) values. In resolve, the
-default value of <name> is your own identity public key.
 
 
 Examples:
@@ -36,7 +32,8 @@ Resolve te value of another name:
 `,
 
 	Arguments: []cmds.Argument{
-		cmds.Argument{"name", cmds.ArgString, false, true},
+		cmds.Argument{"name", cmds.ArgString, false, true,
+			"The IPNS name to resolve. Defaults to your node's peerID."},
 	},
 	Run: func(res cmds.Response, req cmds.Request) {
 

core/commands2/root.go

@@ -1,9 +1,6 @@
 package commands
 
 import (
-	"fmt"
-	"strings"
-
 	cmds "github.com/jbenet/go-ipfs/commands"
 	u "github.com/jbenet/go-ipfs/util"
 )
@@ -16,15 +13,8 @@ type TestOutput struct {
 }
 
 var Root = &cmds.Command{
-	Options: []cmds.Option{
+	Description: "Global P2P Merkle-DAG filesystem",
-		cmds.Option{[]string{"config", "c"}, cmds.String},
+	Help: `Basic commands:
-		cmds.Option{[]string{"debug", "D"}, cmds.Bool},
-		cmds.Option{[]string{"help", "h"}, cmds.Bool},
-		cmds.Option{[]string{"local", "L"}, cmds.Bool},
-	},
-	Help: `ipfs - global versioned p2p merkledag file system
-
-Basic commands:
 
     init          Initialize ipfs local configuration.
     add <path>    Add an object to ipfs.
@@ -53,6 +43,17 @@ Plumbing commands:
 
 Use "ipfs help <command>" for more information about a command.
 `,
+
+	Options: []cmds.Option{
+		cmds.Option{[]string{"config", "c"}, cmds.String,
+			"Path to the configuration file to use"},
+		cmds.Option{[]string{"debug", "D"}, cmds.Bool,
+			"Operate in debug mode"},
+		cmds.Option{[]string{"help", "h"}, cmds.Bool,
+			"Show the command help text"},
+		cmds.Option{[]string{"local", "L"}, cmds.Bool,
+			"Run the command locally, instead of using the daemon"},
+	},
 }
 
 var rootSubcommands = map[string]*cmds.Command{

core/commands2/update.go

@@ -15,14 +15,10 @@ type UpdateOutput struct {
 }
 
 var updateCmd = &cmds.Command{
-	Help: `ipfs update - check for updates and apply them
+	Description: "Downloads and installs updates for IPFS",
-
+	Help: `ipfs update is a utility command used to check for updates and apply them.
-    ipfs update            - apply
-    ipfs update check      - just check
-    ipfs update log        - list the changelogs
-
-ipfs update is a utility command used to check for updates and apply them.
 `,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node
 
@@ -55,7 +51,12 @@ ipfs update is a utility command used to check for updates and apply them.
 }
 
 var updateCheckCmd = &cmds.Command{
-	Help: `ipfs update check <key>`,
+	Description: "Checks if updates are available",
+	Help: `'ipfs update check' checks if any updates are available for IPFS.
+
+Nothing will be downloaded or installed.
+`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node
 
@@ -84,7 +85,10 @@ var updateCheckCmd = &cmds.Command{
 }
 
 var updateLogCmd = &cmds.Command{
-	Help: `ipfs update log - list the last versions and their changelog`,
+	Description: "List the changelog for the latest versions of IPFS",
+	Help: `This command is not yet implemented.
+`,
+
 	Run: func(res cmds.Response, req cmds.Request) {
 		n := req.Context().Node
 
@@ -151,5 +155,6 @@ func updateCheck(n *core.IpfsNode) (*UpdateOutput, error) {
 
 // updateLog lists the version available online
 func updateLog(n *core.IpfsNode) (interface{}, error) {
+	// TODO
 	return nil, errors.New("Not yet implemented")
 }

core/commands2/version.go

@@ -12,13 +12,14 @@ type VersionOutput struct {
 }
 
 var versionCmd = &cmds.Command{
-	Options: []cmds.Option{
+	Description: "Outputs the current version of IPFS",
-		cmds.Option{[]string{"number", "n"}, cmds.Bool},
+	Help: `Returns the version number of IPFS.
-	},
-	Help: `ipfs version - Show ipfs version information.
-
-    Returns the current version of ipfs and exits.
 `,
+
+	Options: []cmds.Option{
+		cmds.Option{[]string{"number", "n"}, cmds.Bool,
+			"Only output the version number"},
+	},
 	Run: func(res cmds.Response, req cmds.Request) {
 		res.SetOutput(&VersionOutput{
 			Version: config.CurrentVersionNumber,