Improve command documentation for listing commands (Fixes #3057).

* Document deprecation of 'ipfs file' in command help.
* Be explicit about 'ipfs ls' listing unixfs and suplying type in JSON.
* Amend description for 'ipfs files ls'.

License: MIT
Signed-off-by: Mathijs de Bruin <mathijs@mathijsfietst.nl>

core/commands/files/files.go

@@ -284,9 +284,9 @@ type FilesLsOutput struct {
 
 var FilesLsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "List directories.",
+		Tagline: "List directories in the local mutable namespace.",
 		ShortDescription: `
-List directories.
+List directories in the local mutable namespace.
 
 Examples:
 

core/commands/ls.go

@@ -32,12 +32,14 @@ type LsOutput struct {
 
 var LsCmd = &cmds.Command{
 	Helptext: cmds.HelpText{
-		Tagline: "List links from an object.",
+		Tagline: "List directory contents for Unix filesystem objects.",
 		ShortDescription: `
-Displays the links an IPFS or IPNS object(s) contains, with the following
-format:
+Displays the contents of an IPFS or IPNS object(s) at the given path, with
+the following format:
 
   <link base58 hash> <link size in bytes> <link name>
+
+The JSON output contains type information.
 `,
 	},
 

core/commands/unixfs/ls.go

@@ -42,6 +42,9 @@ Displays the contents of an IPFS or IPNS object(s) at the given path.
 The JSON output contains size information. For files, the child size
 is the total size of the file contents. For directories, the child
 size is the IPFS link size.
+
+This functionality is deprecated, and will be removed in future versions. If
+possible, please use 'ipfs ls' instead.
 `,
 		LongDescription: `
 Displays the contents of an IPFS or IPNS object(s) at the given path.
@@ -59,6 +62,9 @@ Example:
     cat.jpg
     > ipfs file ls /ipfs/QmW2WQi7j6c7UgJTarActp7tDNikE4B2qXtFCfLPdsgaTQ
     cat.jpg
+
+This functionality is deprecated, and will be removed in future versions. If
+possible, please use 'ipfs ls' instead.
 `,
 	},