rfc: gno doc command

[thehowl]

The underlying idea is to provide roughly the same functionality as the go doc command, as well potentially that of godoc (ie. http documentation viewer/generator).

So the purpose and scope is that to be a central command and reference points to all things related to technical documentation. It should not contain tutorials and guides, but it should contain precise and up-to-date information on all tooling, commands, and specifications related to the Gnolang language.

The way I see it there are a few different types of documentation we should provide:

Standard library ✔️

Examples: gnodev doc errors, gnodev doc std

While most of these can be provided in an identical fashion to how Go doc parses documentation on symbols and packages, there should also be documentation for "native" types which are mapped to go types using stdlibs/stdlibs.go. The way this should be done is by declaring the prototype without the documentation, like Go for does for the symbols implemented in assembly. Providing them directly as prototypes in code also helps to develop future tooling (e.g. code autocompletion, which can be based only on the AST without exceptions for builtin code).

There should also be a documentation-only builtin package, similar to Go's, providing documentation about builtin functions and types.

gnodev tries to determine the directory of stdlibs in the same way as gnodev test currently does, and provides the --root-dir function to that effect. Potentially in the future we could provide some functionality similar to GOROOT, although this is more in the scope of #460.

Local packages and realms ✔️

Examples: gnodev doc ., gnodev doc ./examples/gno.land/p/demo/avl

This should work roughly as the above, parsing the AST with the comments to provide documentation about the package.

References to other packages are parsed and understood in a local context if subpackages of the current (determined through gno.mod). Otherwise, they are understood as remote packages and the --remote flag is used as below (though for CLI usage the remote will not be used).

❓ Should we add further metadata like the one that gnoview displayed, implementing #477?

Remote packages and realms

Examples: gnodev doc --remote 'staging.gno.land:36657' gno.land/p/demo/avl

This should query the remote server for documentation about a package or a realm. So the functionality is similar to that returned by the ABCI query vm/qfuncs - though for this use case there should probably be a specific query which also works on packages and is designed specifically for serving on the documentation (so has raw package documentation and documentation for all the exported symbols, ie. used as a documentation for programming realms instead of for making calls using maketx). Though for the exported functions of a realm, it could provide the same functionality that ?help is currently providing (ie. showing the commands to interact with the contract).

Manually written manual pages

Examples: gnodev man, gnodev man gnokey, gnodev man gnomod, gnodev man abci vm/qeval.

Like UNIX man, but Markdown based. This would pull markdown files as topics from the docs directory in the root, or it could also be built into gnodev using go:embed (possibly guarded by a build tag). So these provide manually written documentation about topics which are related to programming in Gno and using the command line tools of the project. Again, these are not how-tos, but specific documentation about what each flag does.

• Command documentation (gnokey, gnoland, gnofaucet...)
• ABCI query documentation (vm/qeval, vm/qfuncs, ...)
• References (like these: interpreter internals, gnomod, language spec, ...)

HTTP viewer and generator

Considerable when everything else is done and implemented. But many of these references could also be useful to publish online, or simply for users who prefer a graphical interface to view all documentation locally when developing. So the gno.land website could be extended to provide all of the documentation provided in the command gnodev doc and gnodev man, in a similar fashion to what godoc does. This would mean

• expanding ?help to provide also documentation for other symbols which are not smart contracts
• providing a /man sub-path where the manual pages can be found
• providing a way to browse the stdlib source and documentation
• showing ?help also on packages, only to the extent of providing developer documentation (not smart contracts)

Options/functionality overview

• --remote, --root-dir, --home like in other commands.
• --all like go doc (when asking for the documentation of a package, expand all symbols)
• --src like go doc (show the full source code for the symbol)
• --unexported like go doc (show/document unexported symbols, unavailable for remote querying).

For gnodev man, only --root-dir applies

Feedback is very welcome, also on the design of the command line and flags.

---

Related: #28, #379, #408, #477

[moul]

While most of these can be provided in an identical fashion to how Go doc parses documentation on symbols and packages.

We will probably have more metadata at the (see #498), and we should start parsing comments to extend the understanding of packages by our VM and dev tools.

There should also be a documentation-only built-in package, similar to Go's, providing documentation about built-in functions and types.

Yes.

gnodev tries to determine the directory of stdlibs in the same way as gnodev test currently does, and provides the --root-dir function to that effect. Potentially in the future, we could potentially provide some functionality similar to GOROOT, although this is more in the scope of #460.

Yep, also related to gno.mod (#479).

❓ Should we add further metadata like the one that gnoview displayed, implementing #477?

Later yes; short term, no.

The current focus for gnodev should be to support developers working locally.
We have a first basic internet/net dependency feature with gnodev mod download.
Step 1 is to focus on the source code to have something similar to go toolkit.

Step 2 will create and integrate tools to play with the production state, i.e., discovering and inspecting realm data, synchronizing it locally, etc.

Examples: gnodev doc --remote 'staging.gno.land:36657' gno.land/p/demo/avl

Yep, the idea is to make this transparent with the following:

• per-remote caching folder (in $GNOROOT)
• lazy gno mod download when something is missing
• then, make all the commands work locally

HTTP viewer and generator

I love all the enumerated ideas 👍 .

---

Question: do you plan to work on this as a whole, or can you split this into smaller parts?

Thank you

[thehowl]

Smaller parts, roughly matching the 5 paragraphs I would think. So a first POC on the standard library, and then build up from there. Also to keep the PRs small and focused :)

[moul]

We need to enhance our approach to documentation. Here's how:

• Go beyond the basics. Instead of just "documentation is for users," (https://docs.gno.land/concepts/effective-gno/#documentation-is-for-users) let's make our API self-explanatory. Include method signatures, a README.md, developer-suggested examples, and maybe even unit test names, we can create new standards to express documentation from code or .gno files in general. This should help users and developers understand and use the code directly from the source, without needing extra tutorials.

• Integrate documentation with our tools. Make the API docs accessible in GnoWeb. This way, when you run GnoWeb locally, you get all the documentation for installed and developed realms, without needing extra tools or internet access.

• Keep documentation in sync. Embed the docs/ folder from the repo into GnoWeb. This ensures you always have the most up-to-date documentation that matches your current git commit, even offline.

---

In short:

• We aim to improve discoverability, transparency, and trust for users and developers.
• We want a unified development experience. Develop locally, see the results, and update documentation and code in real-time before pushing to GitHub or on-chain. No more guessing the impact of your changes.