Skip to content
This repository was archived by the owner on Sep 9, 2020. It is now read-only.

Commit 4ecb1d1

Browse files
sdboyersdboyer
authored
Merge pull request #1286 from jmank88/cmd_doc
cmd/dep: generate package doc from help command
2 parents 80e94e8 + 4d6a8ae commit 4ecb1d1

File tree

3 files changed

+245
-23
lines changed

3 files changed

+245
-23
lines changed

‎cmd/dep/doc.go

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
// Copyright 2017 The Go Authors. All rights reserved.
2+
// Use of this source code is governed by a BSD-style
3+
// license that can be found in the LICENSE file.
4+
5+
// DO NOT EDIT THIS FILE. GENERATED BY mkdoc.sh.
6+
// Edit the documentation in other files and rerun mkdoc.sh to generate this one.
7+
8+
// Dep is a tool for managing dependencies for Go projects
9+
//
10+
// Usage: "dep [command]"
11+
//
12+
// Commands:
13+
//
14+
// init Initialize a new project with manifest and lock files
15+
// status Report the status of the project's dependencies
16+
// ensure Ensure a dependency is safely vendored in the project
17+
// prune Prune the vendor tree of unused packages
18+
// version Show the dep version information
19+
//
20+
// Examples:
21+
// dep init set up a new project
22+
// dep ensure install the project's dependencies
23+
// dep ensure -update update the locked versions of all dependencies
24+
// dep ensure -add github.com/pkg/errors add a dependency to the project
25+
//
26+
// Use "dep help [command]" for more information about a command.
27+
//
28+
// Initialize a new project with manifest and lock files
29+
//
30+
// Usage:
31+
//
32+
// init [root]
33+
//
34+
// Initialize the project at filepath root by parsing its dependencies, writing
35+
// manifest and lock files, and vendoring the dependencies. If root isn't
36+
// specified, use the current directory.
37+
//
38+
// When configuration for another dependency management tool is detected, it is
39+
// imported into the initial manifest and lock. Use the -skip-tools flag to
40+
// disable this behavior. The following external tools are supported:
41+
// glide, godep, vndr, govend, gb, gvt.
42+
//
43+
// Any dependencies that are not constrained by external configuration use the
44+
// GOPATH analysis below.
45+
//
46+
// By default, the dependencies are resolved over the network. A version will be
47+
// selected from the versions available from the upstream source per the following
48+
// algorithm:
49+
//
50+
// - Tags conforming to semver (sorted by semver rules)
51+
// - Default branch(es) (sorted lexicographically)
52+
// - Non-semver tags (sorted lexicographically)
53+
//
54+
// An alternate mode can be activated by passing -gopath. In this mode, the version
55+
// of each dependency will reflect the current state of the GOPATH. If a dependency
56+
// doesn't exist in the GOPATH, a version will be selected based on the above
57+
// network version selection algorithm.
58+
//
59+
// A Gopkg.toml file will be written with inferred version constraints for all
60+
// direct dependencies. Gopkg.lock will be written with precise versions, and
61+
// vendor/ will be populated with the precise versions written to Gopkg.lock.
62+
//
63+
//
64+
// Report the status of the project's dependencies
65+
//
66+
// Usage:
67+
//
68+
// status [package...]
69+
//
70+
// With no arguments, print the status of each dependency of the project.
71+
//
72+
// PROJECT Import path
73+
// CONSTRAINT Version constraint, from the manifest
74+
// VERSION Version chosen, from the lock
75+
// REVISION VCS revision of the chosen version
76+
// LATEST Latest VCS revision available
77+
// PKGS USED Number of packages from this project that are actually used
78+
//
79+
// With one or more explicitly specified packages, or with the -detailed flag,
80+
// print an extended status output for each dependency of the project.
81+
//
82+
// TODO Another column description
83+
// FOOBAR Another column description
84+
//
85+
// Status returns exit code zero if all dependencies are in a "good state".
86+
//
87+
//
88+
// Ensure a dependency is safely vendored in the project
89+
//
90+
// Usage:
91+
//
92+
// ensure [-update | -add] [-no-vendor | -vendor-only] [-dry-run] [<spec>...]
93+
//
94+
// Project spec:
95+
//
96+
// <import path>[:alt source URL][@<constraint>]
97+
//
98+
//
99+
// Ensure gets a project into a complete, reproducible, and likely compilable state:
100+
//
101+
// * All non-stdlib imports are fulfilled
102+
// * All rules in Gopkg.toml are respected
103+
// * Gopkg.lock records precise versions for all dependencies
104+
// * vendor/ is populated according to Gopkg.lock
105+
//
106+
// Ensure has fast techniques to determine that some of these steps may be
107+
// unnecessary. If that determination is made, ensure may skip some steps. Flags
108+
// may be passed to bypass these checks; -vendor-only will allow an out-of-date
109+
// Gopkg.lock to populate vendor/, and -no-vendor will update Gopkg.lock (if
110+
// needed), but never touch vendor/.
111+
//
112+
// The effect of passing project spec arguments varies slightly depending on the
113+
// combination of flags that are passed.
114+
//
115+
//
116+
// Examples:
117+
//
118+
// dep ensure Populate vendor from existing Gopkg.toml and Gopkg.lock
119+
// dep ensure -add github.com/pkg/foo Introduce a named dependency at its newest version
120+
// dep ensure -add github.com/pkg/foo@^1.0.1 Introduce a named dependency with a particular constraint
121+
//
122+
// For more detailed usage examples, see dep ensure -examples.
123+
//
124+
//
125+
// Prune the vendor tree of unused packages
126+
//
127+
// Usage:
128+
//
129+
// prune
130+
//
131+
// Prune is used to remove unused packages from your vendor tree.
132+
//
133+
// STABILITY NOTICE: this command creates problems for vendor/ verification. As
134+
// such, it may be removed and/or moved out into a separate project later on.
135+
//
136+
//
137+
// Show the dep version information
138+
//
139+
// Usage:
140+
//
141+
// version
142+
//
143+
package main

‎cmd/dep/main.go

Lines changed: 91 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
// Use of this source code is governed by a BSD-style
33
// license that can be found in the LICENSE file.
44

5-
// Command dep is a prototype dependency management tool.
5+
//go:generate ./mkdoc.sh
6+
67
package main
78

89
import (
@@ -89,39 +90,71 @@ func (c *Config) Run() int {
8990
},
9091
}
9192

92-
outLogger := log.New(c.Stdout, "", 0)
93-
errLogger := log.New(c.Stderr, "", 0)
94-
95-
usage := func() {
96-
errLogger.Println("dep is a tool for managing dependencies for Go projects")
97-
errLogger.Println()
98-
errLogger.Println("Usage: dep <command>")
99-
errLogger.Println()
100-
errLogger.Println("Commands:")
101-
errLogger.Println()
102-
w := tabwriter.NewWriter(c.Stderr, 0, 0, 2, ' ', 0)
93+
usage := func(w io.Writer) {
94+
fmt.Fprintln(w, "Dep is a tool for managing dependencies for Go projects")
95+
fmt.Fprintln(w)
96+
fmt.Fprintln(w, "Usage: \"dep [command]\"")
97+
fmt.Fprintln(w)
98+
fmt.Fprintln(w, "Commands:")
99+
fmt.Fprintln(w)
100+
tw := tabwriter.NewWriter(w, 0, 0, 2, ' ', 0)
103101
for _, cmd := range commands {
104102
if !cmd.Hidden() {
105-
fmt.Fprintf(w, "\t%s\t%s\n", cmd.Name(), cmd.ShortHelp())
103+
fmt.Fprintf(tw, "\t%s\t%s\n", cmd.Name(), cmd.ShortHelp())
106104
}
107105
}
108-
w.Flush()
109-
errLogger.Println()
110-
errLogger.Println("Examples:")
106+
tw.Flush()
107+
fmt.Fprintln(w)
108+
fmt.Fprintln(w, "Examples:")
111109
for _, example := range examples {
112-
fmt.Fprintf(w, "\t%s\t%s\n", example[0], example[1])
110+
fmt.Fprintf(tw, "\t%s\t%s\n", example[0], example[1])
113111
}
114-
w.Flush()
115-
errLogger.Println()
116-
errLogger.Println("Use \"dep help [command]\" for more information about a command.")
112+
tw.Flush()
113+
fmt.Fprintln(w)
114+
fmt.Fprintln(w, "Use \"dep help [command]\" for more information about a command.")
117115
}
118116

119117
cmdName, printCommandHelp, exit := parseArgs(c.Args)
120118
if exit {
121-
usage()
119+
usage(c.Stderr)
122120
return errorExitCode
123121
}
124122

123+
// 'dep help documentation' generates doc.go.
124+
if printCommandHelp && cmdName == "documentation" {
125+
fmt.Println("// Copyright 2017 The Go Authors. All rights reserved.")
126+
fmt.Println("// Use of this source code is governed by a BSD-style")
127+
fmt.Println("// license that can be found in the LICENSE file.")
128+
fmt.Println()
129+
fmt.Println("// DO NOT EDIT THIS FILE. GENERATED BY mkdoc.sh.")
130+
fmt.Println("// Edit the documentation in other files and rerun mkdoc.sh to generate this one.")
131+
fmt.Println()
132+
133+
var cw io.Writer = &commentWriter{W: c.Stdout}
134+
usage(cw)
135+
for _, cmd := range commands {
136+
if !cmd.Hidden() {
137+
fmt.Fprintln(cw)
138+
short := cmd.ShortHelp()
139+
fmt.Fprintln(cw, short)
140+
fmt.Fprintln(cw)
141+
fmt.Fprintln(cw, "Usage:")
142+
fmt.Fprintln(cw)
143+
fmt.Fprintln(cw, "", cmd.Name(), cmd.Args())
144+
if long := cmd.LongHelp(); long != short {
145+
fmt.Fprintln(cw, long)
146+
}
147+
}
148+
}
149+
150+
fmt.Println("//")
151+
fmt.Println("package main")
152+
return successExitCode
153+
}
154+
155+
outLogger := log.New(c.Stdout, "", 0)
156+
errLogger := log.New(c.Stderr, "", 0)
157+
125158
for _, cmd := range commands {
126159
if cmd.Name() == cmdName {
127160
// Build flag set with global flags in there.
@@ -170,7 +203,7 @@ func (c *Config) Run() int {
170203
}
171204

172205
errLogger.Printf("dep: %s: no such command\n", cmdName)
173-
usage()
206+
usage(c.Stderr)
174207
return errorExitCode
175208
}
176209

@@ -217,8 +250,9 @@ func parseArgs(args []string) (cmdName string, printCmdUsage bool, exit bool) {
217250
case 2:
218251
if isHelpArg() {
219252
exit = true
253+
} else {
254+
cmdName = args[1]
220255
}
221-
cmdName = args[1]
222256
default:
223257
if isHelpArg() {
224258
cmdName = args[2]
@@ -244,3 +278,37 @@ func getEnv(env []string, key string) string {
244278
}
245279
return ""
246280
}
281+
282+
// commentWriter writes a Go comment to the underlying io.Writer,
283+
// using line comment form (//).
284+
//
285+
// Copied from cmd/go/internal/help/help.go.
286+
type commentWriter struct {
287+
W io.Writer
288+
wroteSlashes bool // Wrote "//" at the beginning of the current line.
289+
}
290+
291+
func (c *commentWriter) Write(p []byte) (int, error) {
292+
var n int
293+
for i, b := range p {
294+
if !c.wroteSlashes {
295+
s := "//"
296+
if b != '\n' {
297+
s = "// "
298+
}
299+
if _, err := io.WriteString(c.W, s); err != nil {
300+
return n, err
301+
}
302+
c.wroteSlashes = true
303+
}
304+
n0, err := c.W.Write(p[i : i+1])
305+
n += n0
306+
if err != nil {
307+
return n, err
308+
}
309+
if b == '\n' {
310+
c.wroteSlashes = false
311+
}
312+
}
313+
return len(p), nil
314+
}

‎cmd/dep/mkdoc.sh

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
#!/bin/bash
2+
# Copyright 2017 The Go Authors. All rights reserved.
3+
# Use of this source code is governed by a BSD-style
4+
# license that can be found in the LICENSE file.
5+
6+
set -e
7+
8+
go build -o dep.latest
9+
./dep.latest help documentation >doc.go
10+
gofmt -w doc.go
11+
rm dep.latest

0 commit comments

Comments
 (0)