upgrade docreflect and allow docreflect for main package symbols

cmd/wand/readme.md

@@ -65,6 +65,8 @@ recommended to use package paths unless there are special circumstances.
 
 #### Options:
 
+- --main bool: indicates that the docs for the symbols will be lookded up as part of the main package of an
+  executable.
 - --help: Show help.
 
 ### wand man
@@ -159,7 +161,7 @@ environment values of the same field are dropped.
 ### Example environment variable:
 
 ```
-WAND_DATE_STRING=42
+WAND_MAIN=true
 ```
 
 ## Configuration:
@@ -193,13 +195,13 @@ contain valid configuration syntax which is wand's flavor of .ini files
 ### Example configuration entry:
 
 ```
-# Default value for --date-string:
-date_string = 42
+# Default value for --main:
+main = true
 ```
 
 ### Example for discarding an inherited entry:
 
 ```
 # Discarding an inherited entry:
-date_string
+main
 ```

docreflect.gen.go

@@ -8,7 +8,9 @@ import "code.squareroundforest.org/arpio/docreflect"
 
 func init() {
 	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", "Docreflect generates documentation from the go docs of a package to be included in the compiled binary and\nto be accessed 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 there are special circumstances.\n\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\nto be accessed 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 there are special circumstances.\n\nfunc(o, out, packageName, gopaths)")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.DocreflectOptions", "DocreflectOption defines options for the docreflect function.\n")
+	docreflect.Register("code.squareroundforest.org/arpio/wand/tools.DocreflectOptions.Main", "Main indicates that the docs for the symbols will be lookded up as part of the main package of an\nexecutable.\n")
 	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 are 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 bash input.\nIt 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", "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", "CacheDir specifies a custom cache dir for wand. Default: ~/.wand.\n")

go.mod

@@ -4,7 +4,7 @@ go 1.25.3
 
 require (
 	code.squareroundforest.org/arpio/bind v0.0.0-20251105181644-3443251be2d5
-	code.squareroundforest.org/arpio/docreflect v0.0.0-20251031192707-01c5ff18fab1
+	code.squareroundforest.org/arpio/docreflect v0.0.0-20260113222846-40bd1879753e
 	code.squareroundforest.org/arpio/notation v0.0.0-20251101123932-5f5c05ee0239
 	code.squareroundforest.org/arpio/textedit v0.0.0-20251207224821-c75c3965789f
 	code.squareroundforest.org/arpio/textfmt v0.0.0-20251207234108-fed32c8bbe18

go.sum

@@ -1,7 +1,7 @@
 code.squareroundforest.org/arpio/bind v0.0.0-20251105181644-3443251be2d5 h1:SIgLIawD6Vv7rAvUobpVshLshdwFEJ0NOUrWpheS088=
 code.squareroundforest.org/arpio/bind v0.0.0-20251105181644-3443251be2d5/go.mod h1:tTCmCwFABKNm3PO0Dclsp4zWhNQFTfg9+uSrgoarZFI=
-code.squareroundforest.org/arpio/docreflect v0.0.0-20251031192707-01c5ff18fab1 h1:bJi41U5yGQykg6jVlD2AdWiznvx3Jg7ZpzEU85syOXw=
-code.squareroundforest.org/arpio/docreflect v0.0.0-20251031192707-01c5ff18fab1/go.mod h1:/3xQI36oJG8qLBxT2fSS61P5/+i1T64fTX9GHRh8XhA=
+code.squareroundforest.org/arpio/docreflect v0.0.0-20260113222846-40bd1879753e h1:Z+TXQtCxNhHUgsBSYsatNGBCRtGibRcsEbZjk1LImCQ=
+code.squareroundforest.org/arpio/docreflect v0.0.0-20260113222846-40bd1879753e/go.mod h1:/3xQI36oJG8qLBxT2fSS61P5/+i1T64fTX9GHRh8XhA=
 code.squareroundforest.org/arpio/html v0.0.0-20251103020946-e262eca50ac9 h1:b7voJlwe0jKH568X+O7b/JTAUrHLTSKNSSL+hhV2Q/Q=
 code.squareroundforest.org/arpio/html v0.0.0-20251103020946-e262eca50ac9/go.mod h1:hq+2CENEd4bVSZnOdq38FUFOJJnF3OTQRv78qMGkNlE=
 code.squareroundforest.org/arpio/notation v0.0.0-20251101123932-5f5c05ee0239 h1:JvLVMuvF2laxXkIZbHC1/0xtKyKndAwIHbIIWkHqTzc=

internal/script/docreflect/docs.go

@@ -11,7 +11,7 @@ func main() {
 		log.Fatalln("expected package name")
 	}
 
-	if err := tools.Docreflect(os.Stdout, os.Args[1], os.Args[2:]...); err != nil {
+	if err := tools.Docreflect(tools.DocreflectOptions{}, os.Stdout, os.Args[1], os.Args[2:]...); err != nil {
 		log.Fatalln(err)
 	}
 }

tools/execwand.go

@@ -282,6 +282,11 @@ func execWand(o ExecOptions, stdin io.Reader, stdout, stderr io.Writer, args []s
 		}
 	}
 
+	var in, out bytes.Buffer
+	if err := execc(&in, &out, stderr, "go mod tidy", nil, nil); err != nil {
+		return err
+	}
+
 	if err := execc(stdin, stdout, stderr, "go run", append([]string{commandDir}, args...), nil); err != nil {
 		return err
 	}

tools/lib.go

@@ -9,6 +9,14 @@ import (
 	"os"
 )
 
+// DocreflectOption defines options for the docreflect function.
+type DocreflectOptions struct {
+
+	// Main indicates that the docs for the symbols will be lookded up as part of the main package of an
+	// executable.
+	Main bool
+}
+
 // ManOptions represents input options for generating man pages for a command created with wand.
 type ManOptions struct {
 
@@ -56,8 +64,9 @@ type ExecOptions struct {
 //
 // The gopath arguments accept any number of package, package level symbol, or struct field paths. It is
 // recommended to use package paths unless there are special circumstances.
-func Docreflect(out io.Writer, packageName string, gopaths ...string) error {
-	return generate.GenerateRegistry(out, packageName, gopaths...)
+func Docreflect(o DocreflectOptions, out io.Writer, packageName string, gopaths ...string) error {
+	genOpt := generate.Options{Main: o.Main}
+	return generate.GenerateRegistry(genOpt, out, packageName, gopaths...)
 }
 
 // Man generates a man page in roff format for a command defined with wand. It relies on the go doc entries

tools/lib_test.go

@@ -8,7 +8,12 @@ import (
 
 func TestDocreflect(t *testing.T) {
 	var b bytes.Buffer
-	if err := tools.Docreflect(&b, "testlib", "code.squareroundforest.org/arpio/wand/internal/tests/testlib"); err != nil {
+	if err := tools.Docreflect(
+		tools.DocreflectOptions{},
+		&b,
+		"testlib",
+		"code.squareroundforest.org/arpio/wand/internal/tests/testlib",
+	); err != nil {
 		t.Fatal(err)
 	}