document the tools package

docreflect.gen.go

@@ -7,22 +7,22 @@ package wand
 import "code.squareroundforest.org/arpio/docreflect"
 
 func init() {
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools", "Package tools provides tools to work with the wand library. The functions in this package serve primarily as\nthe implementation of the wand executable command.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "\nfunc(out, packageName, gopaths)")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Docreflect", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\naccessed by the automatic help and documentation generator.\n\nThe packageName parameter specifies the package name for the generated Go code.\n\nThe gopath arguments accept any number of package, package level symbol, or struct field paths. It is\nrecommended to use package paths unless special circumstances.\n\nfunc(out, packageName, gopaths)")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "\nfunc(o, stdin, stdout, args)")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Exec", "Exec executes a Go function expression parameterized by the subsequent command line arguments.\n\nIt has two modes. When called with arguments, the first argument must be the function expression, and the\nrest of the arguments the command line flags and positional arguments. When no arguments are provided, it\nstarts reading from the input, and considers every line as the expected function expression followed by the\noptions and positional arguments. In the latter case, the escaping is mostly identical to that of the bash\ninput. It keeps executing the input expressions until the input is closed (Ctrl+D).\n\nfunc(o, stdin, stdout, args)")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions", "ExecOptions represents input options for executing a function from the command line using the wand mechanism.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.CacheDir", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.CacheDir", "CacheDir specifies a custom cache dir for wand. Default: ~/.wand.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ClearCache", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ClearCache", "ClearCache clears the cached artifacts resulting from a previous execution before the current execution.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.Import", "Import lists the packages required for the expression to be executed. It accepts versioned package\nspecifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will\nimport the for the expression with the specified alias or inline.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.NoCache", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.NoCache", "NoCache causes the execution to avoid relying on the cached artifacts resulting from a previous\nexecution.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ExecOptions.ReplaceModule", "ReplaceModule replaces imported go modules with local or other versions of the given modules. The format\nof the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Man", "\nfunc(out, o, commandDir)")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Man", "Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries\nextracted by Docreflect.\n\nfunc(out, o, commandDir)")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions", "ManOptions represents input options for generating man pages for a command created with wand.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.DateString", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.DateString", "DateString provides the value for the release date field in a man page.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.Version", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.ManOptions.Version", "Version provides the value for the release version field in a man page.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Markdown", "\nfunc(out, o, commandDir)")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.Markdown", "Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by\nDocreflect.\n\nfunc(out, o, commandDir)")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions", "MarkdownOptions represents input options for generating markdown documents for a command created with wand.\n")
-	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions.Level", "")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.MarkdownOptions.Level", "Level provides a default title level offset for the titles in a markdown document.\n")
 	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.commandReader", "\nfunc(in)")
 	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execCommandDir", "\nfunc(out, commandDir, env)")
 	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.execInput", "\nfunc(o, stdin, stdout, stderr, args)")

tools/execwand.go

@@ -17,14 +17,6 @@ import (
 
 const selfPkg = "code.squareroundforest.org/arpio/wand"
 
-type ExecOptions struct {
-	NoCache       bool
-	ClearCache    bool
-	CacheDir      string
-	Import        []string
-	ReplaceModule []string
-}
-
 func commandReader(in io.Reader) func() ([]string, error) {
 	var (
 		yieldErr                             error
@@ -332,7 +324,3 @@ func execInput(o ExecOptions, stdin io.Reader, stdout, stderr io.Writer, args ..
 
 	return execWand(o, stdin, stdout, stderr, args)
 }
-
-func Exec(o ExecOptions, stdin io.Reader, stdout io.Writer, args ...string) error {
-	return execInput(o, stdin, stdout, os.Stderr, args...)
-}

tools/lib.go

@@ -1,24 +1,67 @@
+// Package tools provides tools to work with the wand library. The functions in this package serve primarily as
+// the implementation of the wand executable command.
 package tools
 
 import (
 	"code.squareroundforest.org/arpio/docreflect/generate"
 	"fmt"
 	"io"
+	"os"
 )
 
+// ManOptions represents input options for generating man pages for a command created with wand.
 type ManOptions struct {
+
+	// DateString provides the value for the release date field in a man page.
 	DateString string
+
+	// Version provides the value for the release version field in a man page.
 	Version string
 }
 
+// MarkdownOptions represents input options for generating markdown documents for a command created with wand.
 type MarkdownOptions struct {
+
+	// Level provides a default title level offset for the titles in a markdown document.
 	Level int
 }
 
+// ExecOptions represents input options for executing a function from the command line using the wand mechanism.
+type ExecOptions struct {
+
+	// NoCache causes the execution to avoid relying on the cached artifacts resulting from a previous
+	// execution.
+	NoCache bool
+
+	// ClearCache clears the cached artifacts resulting from a previous execution before the current execution.
+	ClearCache bool
+
+	// CacheDir specifies a custom cache dir for wand. Default: ~/.wand.
+	CacheDir string
+
+	// Import lists the packages required for the expression to be executed. It accepts versioned package
+	// specifications, or it uses the latest version. When a package spec is prefixed with alias= or .=, it will
+	// import the for the expression with the specified alias or inline.
+	Import []string
+
+	// ReplaceModule replaces imported go modules with local or other versions of the given modules. The format
+	// of the items is: <module-path>=<replacement-module-path>, like for the go mod edit -replace command.
+	ReplaceModule []string
+}
+
+// Docreflect generates documentation from the go docs of a package to be included in the compiled binary and
+// accessed by the automatic help and documentation generator.
+//
+// The packageName parameter specifies the package name for the generated Go code.
+//
+// The gopath arguments accept any number of package, package level symbol, or struct field paths. It is
+// recommended to use package paths unless special circumstances.
 func Docreflect(out io.Writer, packageName string, gopaths ...string) error {
 	return generate.GenerateRegistry(out, packageName, gopaths...)
 }
 
+// Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries
+// extracted by Docreflect.
 func Man(out io.Writer, o ManOptions, commandDir string) error {
 	return execCommandDir(
 		out,
@@ -29,6 +72,8 @@ func Man(out io.Writer, o ManOptions, commandDir string) error {
 	)
 }
 
+// Man generates a markdown page for a command defined with wand. It relies on the go doc entries extracted by
+// Docreflect.
 func Markdown(out io.Writer, o MarkdownOptions, commandDir string) error {
 	return execCommandDir(
 		out,
@@ -37,3 +82,14 @@ func Markdown(out io.Writer, o MarkdownOptions, commandDir string) error {
 		fmt.Sprintf("_wandmarkdownlevel=%d", o.Level),
 	)
 }
+
+// Exec executes a Go function expression parameterized by the subsequent command line arguments.
+//
+// It has two modes. When called with arguments, the first argument must be the function expression, and the
+// rest of the arguments the command line flags and positional arguments. When no arguments are provided, it
+// starts reading from the input, and considers every line as the expected function expression followed by the
+// options and positional arguments. In the latter case, the escaping is mostly identical to that of the bash
+// input. It keeps executing the input expressions until the input is closed (Ctrl+D).
+func Exec(o ExecOptions, stdin io.Reader, stdout io.Writer, args ...string) error {
+	return execInput(o, stdin, stdout, os.Stderr, args...)
+}