From 514cd3375d96e274e4f3e4cda99e9b4a7d1f4ca6 Mon Sep 17 00:00:00 2001 From: Arpad Ryszka Date: Tue, 13 Jan 2026 23:54:51 +0100 Subject: [PATCH] upgrade docreflect and allow docreflect for main package symbols --- cmd/wand/readme.md | 10 ++++++---- docreflect.gen.go | 4 +++- go.mod | 2 +- go.sum | 4 ++-- internal/script/docreflect/docs.go | 2 +- tools/execwand.go | 5 +++++ tools/lib.go | 13 +++++++++++-- tools/lib_test.go | 7 ++++++- 8 files changed, 35 insertions(+), 12 deletions(-) diff --git a/cmd/wand/readme.md b/cmd/wand/readme.md index 3e09db5..b2a6c25 100644 --- a/cmd/wand/readme.md +++ b/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 ``` diff --git a/docreflect.gen.go b/docreflect.gen.go index ceb9ef8..146e812 100644 --- a/docreflect.gen.go +++ b/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") diff --git a/go.mod b/go.mod index 44da9df..d0fe250 100644 --- a/go.mod +++ b/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 diff --git a/go.sum b/go.sum index 1984a7b..c3e4f02 100644 --- a/go.sum +++ b/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= diff --git a/internal/script/docreflect/docs.go b/internal/script/docreflect/docs.go index cc0e6e2..bedc3de 100644 --- a/internal/script/docreflect/docs.go +++ b/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) } } diff --git a/tools/execwand.go b/tools/execwand.go index 129022c..d8c915a 100644 --- a/tools/execwand.go +++ b/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 } diff --git a/tools/lib.go b/tools/lib.go index f7f7d3a..eb2a855 100644 --- a/tools/lib.go +++ b/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 diff --git a/tools/lib_test.go b/tools/lib_test.go index 28db554..6790285 100644 --- a/tools/lib_test.go +++ b/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) }