digraph: clean up docs, usage, copyright

- Move verbose usage docs to godoc, replace usage with terse description of
usage and commands.
- Add copyrights.
- Update usage to more canonical function format instead of const format.

Change-Id: I30d072f391bbf9911798e90efb85cd5351d99205
Reviewed-on: https://go-review.googlesource.com/c/tools/+/184177
Run-TryBot: Alan Donovan <adonovan@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Alan Donovan <adonovan@google.com>

cmd/digraph/digraph.go

@@ -1,18 +1,83 @@
-// The digraph command performs queries over unlabelled directed graphs
+// Copyright 2019 The Go Authors. All rights reserved.
-// represented in text form.  It is intended to integrate nicely with
+// Use of this source code is governed by a BSD-style
-// typical UNIX command pipelines.
+// license that can be found in the LICENSE file.
-//
+
-// Since directed graphs (import graphs, reference graphs, call graphs,
+/*
-// etc) often arise during software tool development and debugging, this
+The digraph command performs queries over unlabelled directed graphs
-// command is included in the go.tools repository.
+represented in text form.  It is intended to integrate nicely with
-//
+typical UNIX command pipelines.
+
+Usage:
+
+	your-application | digraph [command]
+
+The support commands are:
+
+	nodes
+		the set of all nodes
+	degree
+		the in-degree and out-degree of each node
+	preds <node> ...
+		the set of immediate predecessors of the specified nodes
+	succs <node> ...
+		the set of immediate successors of the specified nodes
+	forward <node> ...
+		the set of nodes transitively reachable from the specified nodes
+	reverse <node> ...
+		the set of nodes that transitively reach the specified nodes
+	somepath <node> <node>
+		the list of nodes on some arbitrary path from the first node to the second
+	allpaths <node> <node>
+		the set of nodes on all paths from the first node to the second
+	sccs
+		all strongly connected components (one per line)
+	scc <node>
+		the set of nodes nodes strongly connected to the specified one
+
+Input format:
+
+Each line contains zero or more words. Words are separated by unquoted
+whitespace; words may contain Go-style double-quoted portions, allowing spaces
+and other characters to be expressed.
+
+Each word declares a node, and if there are more than one, an edge from the
+first to each subsequent one. The graph is provided on the standard input.
+
+For instance, the following (acyclic) graph specifies a partial order among the
+subtasks of getting dressed:
+
+	$ cat clothes.txt
+	socks shoes
+	"boxer shorts" pants
+	pants belt shoes
+	shirt tie sweater
+	sweater jacket
+	hat
+
+The line "shirt tie sweater" indicates the two edges shirt -> tie and
+shirt -> sweater, not shirt -> tie -> sweater.
+
+Example usage:
+
+Using digraph with existing Go tools:
+
+	$ go mod graph | digraph nodes # Operate on the Go module graph.
+	$ go list -m all | digraph nodes # Operate on the Go package graph.
+
+Show the transitive closure of imports of the digraph tool itself:
+	$ go list -f '{{.ImportPath}} {{join .Imports " "}}' ... | digraph forward golang.org/x/tools/cmd/digraph
+
+Show which clothes (see above) must be donned before a jacket:
+	$ digraph reverse jacket
+
+*/
+package main // import "golang.org/x/tools/cmd/digraph"
+
 // TODO(adonovan):
 // - support input files other than stdin
 // - support alternative formats (AT&T GraphViz, CSV, etc),
 //   a comment syntax, etc.
 // - allow queries to nest, like Blaze query language.
-//
-package main // import "golang.org/x/tools/cmd/digraph"
 
 import (
 	"bufio"
@@ -28,74 +93,41 @@ import (
 	"unicode/utf8"
 )
 
-const Usage = `digraph: queries over directed graphs in text form.
+func usage() {
+	fmt.Fprintf(os.Stderr, `Usage: your-application | digraph [command]
 
-Graph format:
+The support commands are:
-
+	nodes
-  Each line contains zero or more words.  Words are separated by
+		the set of all nodes
-  unquoted whitespace; words may contain Go-style double-quoted portions,
+	degree
-  allowing spaces and other characters to be expressed.
+		the in-degree and out-degree of each node
-
+	preds <node> ...
-  Each field declares a node, and if there are more than one,
+		the set of immediate predecessors of the specified nodes
-  an edge from the first to each subsequent one.
+	succs <node> ...
-  The graph is provided on the standard input.
+		the set of immediate successors of the specified nodes
-
+	forward <node> ...
-  For instance, the following (acyclic) graph specifies a partial order
+		the set of nodes transitively reachable from the specified nodes
-  among the subtasks of getting dressed:
+	reverse <node> ...
-
+		the set of nodes that transitively reach the specified nodes
-	% cat clothes.txt
+	somepath <node> <node>
-	socks shoes
+		the list of nodes on some arbitrary path from the first node to the second
-	"boxer shorts" pants
+	allpaths <node> <node>
-	pants belt shoes
+		the set of nodes on all paths from the first node to the second
-	shirt tie sweater
+	sccs
-	sweater jacket
+		all strongly connected components (one per line)
-	hat
+	scc <node>
-
+		the set of nodes nodes strongly connected to the specified one
-  The line "shirt tie sweater" indicates the two edges shirt -> tie and
+`)
-  shirt -> sweater, not shirt -> tie -> sweater.
+	os.Exit(2)
-
+}
-Supported queries:
-
-  nodes
-	the set of all nodes
-  degree
-	the in-degree and out-degree of each node.
-  preds <label> ...
-	the set of immediate predecessors of the specified nodes
-  succs <label> ...
-	the set of immediate successors of the specified nodes
-  forward <label> ...
-	the set of nodes transitively reachable from the specified nodes
-  reverse <label> ...
-	the set of nodes that transitively reach the specified nodes
-  somepath <label> <label>
-	the list of nodes on some arbitrary path from the first node to the second
-  allpaths <label> <label>
-	the set of nodes on all paths from the first node to the second
-  sccs
-	all strongly connected components (one per line)
-  scc <label>
-	the set of nodes nodes strongly connected to the specified one
-
-Example usage:
-
-   Show the transitive closure of imports of the digraph tool itself:
-   % go list -f '{{.ImportPath}}{{.Imports}}' ... | tr '[]' '  ' |
-         digraph forward golang.org/x/tools/cmd/digraph
-
-   Show which clothes (see above) must be donned before a jacket:
-   %  digraph reverse jacket <clothes.txt
-
-`
 
 func main() {
-	flag.Usage = func() { fmt.Fprintln(os.Stderr, Usage) }
+	flag.Usage = usage
 	flag.Parse()
 
 	args := flag.Args()
 	if len(args) == 0 {
-		fmt.Fprintln(os.Stderr, Usage)
+		usage()
-		return
 	}
 
 	if err := digraph(args[0], args[1:]); err != nil {

cmd/digraph/digraph_test.go

@@ -1,3 +1,7 @@
+// Copyright 2019 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
 package main
 
 import (