ref: Add short description to godoc headers.
The auto-generated doc.go file for cmdline tools is formatted
specially so that godoc will interpret each command as a header,
which gets automatically linked to a table of contents. This
change adds the short description from each command or help
topic, to make the TOC more useful.
Note that godoc has heurisitics for what it considers an
appropriate header; e.g. if the line contains certain puncutation
it won't be extracted as a header. For these cases we fall back
and only use the command path, since it's better to have a less
descriptive header than to have no header at all.
Also added LineWriter.ForceVerbatim, which lets us force verbatim
mode. This is used to ensure the header line we generate isn't
wrapped into more than one line.
MultiPart: 3/3
Change-Id: I7f797d2f3945e3b1ff55bc513a9a8bd2d98a5e8c
diff --git a/cmd/mounttable/doc.go b/cmd/mounttable/doc.go
index 0dd113d..81aa724 100644
--- a/cmd/mounttable/doc.go
+++ b/cmd/mounttable/doc.go
@@ -61,7 +61,7 @@
-vmodule=
comma-separated list of pattern=N settings for file-filtered logging
-Mounttable glob
+Mounttable glob - returns all matching entries in the mount table
returns all matching entries in the mount table
@@ -108,7 +108,7 @@
<mount name> is a mount name on a mount table.
-Mounttable help
+Mounttable help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmd/namespace/doc.go b/cmd/namespace/doc.go
index d873fb4..407a1c8 100644
--- a/cmd/namespace/doc.go
+++ b/cmd/namespace/doc.go
@@ -69,7 +69,7 @@
-vmodule=
comma-separated list of pattern=N settings for file-filtered logging
-Namespace glob
+Namespace glob - Returns all matching entries from the namespace
Returns all matching entries from the namespace.
@@ -83,7 +83,7 @@
-l=false
Long listing format.
-Namespace mount
+Namespace mount - Adds a server to the namespace
Adds server <server> to the namespace with name <name>.
@@ -95,7 +95,7 @@
followed by a unit suffix (s, m, h). A value of 0s represents an infinite
duration.
-Namespace unmount
+Namespace unmount - Removes a server from the namespace
Removes server <server> with name <name> from the namespace.
@@ -119,7 +119,7 @@
Insecure mode: May return results from untrusted servers and invoke Resolve
on untrusted mounttables
-Namespace resolvetomt
+Namespace resolvetomt - Finds the address of the mounttable that holds an object name
Finds the address of the mounttable that holds an object name.
@@ -133,7 +133,7 @@
Insecure mode: May return results from untrusted servers and invoke Resolve
on untrusted mounttables
-Namespace permissions
+Namespace permissions - Manipulates permissions on an entry in the namespace
Commands to get and set the permissions on a name - controlling the blessing
names required to resolve the name.
@@ -148,7 +148,7 @@
get Gets permissions on a mount name
set Sets permissions on a mount name
-Namespace permissions get
+Namespace permissions get - Gets permissions on a mount name
Get retrieves the permissions on the usage of a name.
@@ -160,7 +160,7 @@
<name> is a name in the namespace.
-Namespace permissions set
+Namespace permissions set - Sets permissions on a mount name
Set replaces the permissions controlling usage of a mount name.
@@ -172,7 +172,7 @@
<permissions> is the path to a file containing a JSON-encoded Permissions object
(defined in v.io/v23/security/access/types.vdl), or "-" for STDIN.
-Namespace delete
+Namespace delete - Deletes a name from the namespace
Deletes a name from the namespace.
@@ -185,7 +185,7 @@
-r=false
Delete all children of the name in addition to the name itself.
-Namespace help
+Namespace help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmd/principal/doc.go b/cmd/principal/doc.go
index 4910fb7..987d821 100644
--- a/cmd/principal/doc.go
+++ b/cmd/principal/doc.go
@@ -77,7 +77,7 @@
-vmodule=
comma-separated list of pattern=N settings for file-filtered logging
-Principal create
+Principal create - Create a new principal and persist it into a directory
Creates a new principal with a single self-blessed blessing and writes it out to
the provided directory. The same directory can then be used to set the
@@ -99,7 +99,7 @@
-overwrite=false
If true, any existing principal data in the directory will be overwritten
-Principal fork
+Principal fork - Fork a new principal from the principal that this tool is running as and persist it into a directory
Creates a new principal with a blessing from the principal specified by the
environment that this tool is running in, and writes it out to the provided
@@ -134,7 +134,7 @@
-with=
Path to file containing blessing to extend
-Principal seekblessings
+Principal seekblessings - Seek blessings from a web-based Vanadium blessing service
Seeks blessings from a web-based Vanadium blesser which requires the caller to
first authenticate with Google using OAuth. Simply run the command to see what
@@ -166,7 +166,7 @@
If true, the blessings obtained will be set as the default blessing in the
store
-Principal recvblessings
+Principal recvblessings - Receive blessings sent by another principal and use them as the default
Allow another principal (likely a remote process) to bless this one.
@@ -217,7 +217,7 @@
If true, the blessings received will be set as the default blessing in the
store
-Principal dump
+Principal dump - Dump out information about the principal
Prints out information about the principal specified by the environment that
this tool is running in.
@@ -229,7 +229,7 @@
-s=false
If true, show only the default blessing names
-Principal dumpblessings
+Principal dumpblessings - Dump out information about the provided blessings
Prints out information about the blessings (typically obtained from this tool)
encoded in the provided file.
@@ -240,7 +240,7 @@
<file> is the path to a file containing blessings typically obtained from this
tool. - is used for STDIN.
-Principal blessself
+Principal blessself - Generate a self-signed blessing
Returns a blessing with name <name> and self-signed by the principal specified
by the environment that this tool is running in. Optionally, the blessing can be
@@ -260,7 +260,7 @@
-for=0
Duration of blessing validity (zero implies no expiration)
-Principal bless
+Principal bless - Bless another principal
Bless another principal.
@@ -334,7 +334,7 @@
default Set provided blessings as default
forpeer Set provided blessings for peer
-Principal set default
+Principal set default - Set provided blessings as default
Sets the provided blessings as default in the BlessingStore specified by the
environment that this tool is running in.
@@ -353,7 +353,7 @@
If true, the root certificate of the blessing will be added to the
principal's set of recognized root certificates
-Principal set forpeer
+Principal set forpeer - Set provided blessings for peer
Marks the provided blessings to be shared with the provided peers on the
BlessingStore specified by the environment that this tool is running in.
@@ -398,7 +398,7 @@
peermap Shows the map from peer pattern to which blessing name to
present.
-Principal get default
+Principal get default - Return blessings marked as default
Returns blessings that are marked as default in the BlessingStore specified by
the environment that this tool is running in. Providing --names will print the
@@ -417,7 +417,7 @@
-rootkey=
Shows the value of the root key of the provided certificate chain name.
-Principal get forpeer
+Principal get forpeer - Return blessings marked for the provided peer
Returns blessings that are marked for the provided peer in the BlessingStore
specified by the environment that this tool is running in. Providing --names
@@ -482,7 +482,7 @@
Usage:
principal get peermap
-Principal recognize
+Principal recognize - Add to the set of identity providers recognized by this principal
Adds an identity provider to the set of recognized roots public keys for this
principal.
@@ -510,7 +510,7 @@
<blessing pattern> is the blessing pattern for which <key> should be recognized.
-Principal help
+Principal help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmd/uniqueid/doc.go b/cmd/uniqueid/doc.go
index 08b1405..f835eb3 100644
--- a/cmd/uniqueid/doc.go
+++ b/cmd/uniqueid/doc.go
@@ -21,14 +21,14 @@
-v23.metadata=<just specify -v23.metadata to activate>
Displays metadata for the program and exits.
-Uniqueid generate
+Uniqueid generate - Generates UniqueIds
Generates unique ids and outputs them to standard out.
Usage:
uniqueid generate
-Uniqueid inject
+Uniqueid inject - Injects UniqueIds into existing files
Injects UniqueIds into existing files. Strings of the form "$UNIQUEID$" will be
replaced with generated ids.
@@ -38,7 +38,7 @@
<filenames> List of files to inject unique ids into
-Uniqueid help
+Uniqueid help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmd/vdl/doc.go b/cmd/vdl/doc.go
index f06e0e8..7307617 100644
--- a/cmd/vdl/doc.go
+++ b/cmd/vdl/doc.go
@@ -110,7 +110,7 @@
-status=true
Show package names while we compile
-Vdl audit
+Vdl audit - Check if any packages are stale and need generation
Audit runs the same logic as generate, but doesn't write out generated files.
Returns a 0 exit code if all packages are up-to-date, otherwise returns a non-0
@@ -165,7 +165,7 @@
-status=true
Show package names as they are updated
-Vdl list
+Vdl list - List package and dependency info in transitive order
List returns information about packages and their transitive dependencies, in
transitive order. This is the same order the generate and compile commands use
@@ -184,7 +184,7 @@
<packages> are a list of packages to process, similar to the standard go tool.
For more information, run "vdl help packages".
-Vdl help
+Vdl help - Display help for commands or topics
Help with no args displays the usage of the parent command.
@@ -209,7 +209,7 @@
Defaults to the terminal width if available. Override the default by setting
the CMDLINE_WIDTH environment variable.
-Vdl packages - help topic
+Vdl packages - Description of package lists
Most vdl commands apply to a list of packages:
@@ -237,7 +237,7 @@
Run "vdl help vdlpath" to see docs on VDLPATH.
Run "go help packages" to see the standard go package docs.
-Vdl vdlpath - help topic
+Vdl vdlpath - Description of VDLPATH environment variable
The VDLPATH environment variable is used to resolve import statements. It must
be set to compile and generate vdl packages.
@@ -263,7 +263,7 @@
baz/ (import "bar/baz" refers here)
baz.vdl
-Vdl vdlroot - help topic
+Vdl vdlroot - Description of VDLROOT environment variable
The VDLROOT environment variable is similar to VDLPATH, but instead of pointing
to multiple user source directories, it points at a single source directory
@@ -274,7 +274,7 @@
If VDLROOT is empty, we try to construct it out of the V23_ROOT environment
variable. It is an error if both VDLROOT and V23_ROOT are empty.
-Vdl vdl.config - help topic
+Vdl vdl.config
Each vdl source package P may contain an optional file "vdl.config" within the P
directory. This file specifies additional configuration for the vdl tool.
diff --git a/cmd/vom/doc.go b/cmd/vom/doc.go
index e34f185..dc1e047 100644
--- a/cmd/vom/doc.go
+++ b/cmd/vom/doc.go
@@ -20,7 +20,7 @@
-v23.metadata=<just specify -v23.metadata to activate>
Displays metadata for the program and exits.
-Vom decode
+Vom decode - Decode data encoded in the vom format
Decode decodes data encoded in the vom format. If no arguments are provided,
decode reads the data from stdin, otherwise the argument is the data.
@@ -38,7 +38,7 @@
-data=Hex
Data representation, one of [Hex Binary]
-Vom dump
+Vom dump - Dump data encoded in the vom format into formatted output
Dump dumps data encoded in the vom format, generating formatted output
describing each portion of the encoding. If no arguments are provided, dump
@@ -68,7 +68,7 @@
-data=Hex
Data representation, one of [Hex Binary]
-Vom help
+Vom help - Display help for commands or topics
Help with no args displays the usage of the parent command.
diff --git a/cmd/vrpc/doc.go b/cmd/vrpc/doc.go
index fc183f9..7210979 100644
--- a/cmd/vrpc/doc.go
+++ b/cmd/vrpc/doc.go
@@ -61,7 +61,7 @@
-vmodule=
comma-separated list of pattern=N settings for file-filtered logging
-Vrpc signature
+Vrpc signature - Describe the interfaces of a Vanadium server
Signature connects to the Vanadium server identified by <server>.
@@ -84,7 +84,7 @@
-show-reserved=false
if true, also show the signatures of reserved methods
-Vrpc call
+Vrpc call - Call a method of a Vanadium server
Call connects to the Vanadium server identified by <server> and calls the
<method> with the given positional [args...], returning results on stdout.
@@ -114,7 +114,7 @@
[args...] are the positional input arguments, specified as VDL expressions.
-Vrpc identify
+Vrpc identify - Reveal blessings presented by a Vanadium server
Identify connects to the Vanadium server identified by <server> and dumps out
the blessings presented by that server (and the subset of those that are
@@ -131,7 +131,7 @@
If true, skip server authentication. This means that the client will reveal
its blessings to servers that it may not recognize.
-Vrpc help
+Vrpc help - Display help for commands or topics
Help with no args displays the usage of the parent command.
