feat: Add vm/qdoc with function comments

docs/gno-tooling/cli/gnokey/querying-a-network.md

@@ -24,6 +24,7 @@ Below is a list of queries a user can make with `gnokey`:
 - `bank/balances/{ADDRESS}` - returns balances of an account
 - `vm/qfuncs` - returns the exported functions for a given pkgpath
 - `vm/qfile` - returns package contents for a given pkgpath
+- `vm/qdoc` - Returns the JSON of the doc for a given pkgpath, suitable for printing
 - `vm/qeval` - evaluates an expression in read-only mode on and returns the results
 - `vm/qrender` - shorthand for evaluating `vm/qeval Render("")` for a given pkgpath
 
@@ -176,6 +177,77 @@ const (
 ...
 ```
 
+
+## `vm/qdoc`
+
+Using the `vm/qdoc` query, we can fetch the docs, for functions, types and variables from a specific
+package path. To specify the path we want to query, we can use the `-data` flag:
+
+```bash
+gnokey query vm/qdoc --data "gno.land/r/gnoland/valopers/v2" -remote https://rpc.gno.land:443
+```
+
+The output is a JSON string containing doc strings of the package, functions, etc., including comments for `valopers` realm:
+
+```json
+height: 0
+data: {
+  "package_path": "gno.land/r/gnoland/valopers/v2",
+  "package_line": "package valopers // import \"valopers\"",
+  "package_doc": "Package valopers is designed around the permissionless lifecycle of valoper profiles. It also includes parts designed for govdao to propose valset changes based on registered valopers.\n",
+  "values": [
+    {
+      "name": "valopers",
+      "doc": "// Address -> Valoper\n",
+      "type": "*avl.Tree"
+    }
+    // other values
+  ],
+  "funcs": [
+    {
+      "type": "",
+      "name": "GetByAddr",
+      "signature": "func GetByAddr(address std.Address) Valoper",
+      "doc": "GetByAddr fetches the valoper using the address, if present\n",
+      "params": [
+        {
+          "Name": "address",
+          "Type": "std.Address"
+        }
+      ],
+      "results": [
+        {
+          "Name": "",
+          "Type": "Valoper"
+        }
+      ]
+    }
+    // other funcs
+    {
+      "type": "Valoper",
+      "name": "Render",
+      "signature": "func (v Valoper) Render() string",
+      "doc": "Render renders a single valoper with their information\n",
+      "params": [],
+      "results": [
+        {
+          "Name": "",
+          "Type": "string"
+        }
+      ]
+    }
+    // other methods (in this case of the Valoper type)
+  ],
+  "types": [
+    {
+      "name": "Valoper",
+      "signature": "type Valoper struct {\n\tName        string // the display name of the valoper\n\tMoniker     string // the moniker of the valoper\n\tDescription string // the description of the valoper\n\n\tAddress      std.Address // The bech32 gno address of the validator\n\tPubKey       string      // the bech32 public key of the validator\n\tP2PAddresses []string    // the publicly reachable P2P addresses of the validator\n\tActive       bool        // flag indicating if the valoper is active\n}",
+      "doc": "Valoper represents a validator operator profile\n"
+    }
+  ]
+}
+```
+
 ## `vm/qeval`
 
 `vm/qeval` allows us to evaluate a call to an exported function without using gas,

docs/reference/rpc-endpoints.md

@@ -459,6 +459,7 @@ Call with the `/abci_query` to get information via the ABCI Query.
 | `bank/balances/{ADDRESS}` | Returns the balance information about the account.                 |
 | `vm/qfuncs`               | Returns public facing function signatures as JSON.                 |
 | `vm/qfile`                | Returns the file bytes, or list of files if directory.             |
+| `vm/qdoc`                 | Returns JSON of the package doc, suitable for printing.            |
 | `vm/qrender`              | Calls `.Render(<path>)` in readonly mode.                          |
 | `vm/qeval`                | Evaluates any expression in readonly mode and returns the results. |
 | `vm/store`                | (not yet supported) Fetches items from the store.                  |

gno.land/pkg/sdk/vm/handler.go

@@ -72,6 +72,7 @@ const (
 	QueryFuncs  = "qfuncs"
 	QueryEval   = "qeval"
 	QueryFile   = "qfile"
+	QueryDoc    = "qdoc"
 )
 
 func (vh vmHandler) Query(ctx sdk.Context, req abci.RequestQuery) abci.ResponseQuery {
@@ -89,6 +90,8 @@ func (vh vmHandler) Query(ctx sdk.Context, req abci.RequestQuery) abci.ResponseQ
 		res = vh.queryEval(ctx, req)
 	case QueryFile:
 		res = vh.queryFile(ctx, req)
+	case QueryDoc:
+		res = vh.queryDoc(ctx, req)
 	default:
 		return sdk.ABCIResponseQueryFromError(
 			std.ErrUnknownRequest(fmt.Sprintf(
@@ -183,6 +186,18 @@ func (vh vmHandler) queryFile(ctx sdk.Context, req abci.RequestQuery) (res abci.
 	return
 }
 
+// queryDoc returns the JSON of the doc for a given pkgpath, suitable for printing
+func (vh vmHandler) queryDoc(ctx sdk.Context, req abci.RequestQuery) (res abci.ResponseQuery) {
+	filepath := string(req.Data)
+	jsonDoc, err := vh.vm.QueryDoc(ctx, filepath)
+	if err != nil {
+		res = sdk.ABCIResponseQueryFromError(err)
+		return
+	}
+	res.Data = []byte(jsonDoc.JSON())
+	return
+}
+
 // ----------------------------------------
 // misc
 

gno.land/pkg/sdk/vm/handler_test.go

@@ -5,6 +5,7 @@ import (
 	"testing"
 
 	"github.com/gnolang/gno/gnovm"
+	"github.com/gnolang/gno/gnovm/pkg/doc"
 	abci "github.com/gnolang/gno/tm2/pkg/bft/abci/types"
 	"github.com/gnolang/gno/tm2/pkg/crypto"
 	"github.com/gnolang/gno/tm2/pkg/std"
@@ -327,3 +328,118 @@ func TestVmHandlerQuery_File(t *testing.T) {
 		})
 	}
 }
+
+func TestVmHandlerQuery_Doc(t *testing.T) {
+	expected := &doc.JSONDocumentation{
+		PackagePath: "gno.land/r/hello",
+		PackageLine: "package hello // import \"hello\"",
+		PackageDoc:  "hello is a package for testing\n",
+		Values: []*doc.JSONValueDecl{
+			{
+				Signature: "const prefix = \"Hello\"",
+				Const:     true,
+				Doc:       "The prefix for the hello message\n",
+				Values: []*doc.JSONValue{
+					{
+						Name: "prefix",
+						Doc:  "",
+						Type: "",
+					},
+				},
+			},
+		},
+		Funcs: []*doc.JSONFunc{
+			{
+				Type:      "",
+				Name:      "Hello",
+				Signature: "func Hello(msg string) (res string)",
+				Doc:       "",
+				Params: []*doc.JSONField{
+					{Name: "msg", Type: "string"},
+				},
+				Results: []*doc.JSONField{
+					{Name: "res", Type: "string"},
+				},
+			},
+			{
+				Type:      "myStruct",
+				Name:      "Foo",
+				Signature: "func (ms myStruct) Foo() string",
+				Doc:       "",
+				Params:    []*doc.JSONField{},
+				Results: []*doc.JSONField{
+					{Name: "", Type: "string"},
+				},
+			},
+		},
+		Types: []*doc.JSONType{
+			{
+				Name:      "myStruct",
+				Signature: "type myStruct struct{ a int }",
+				Doc:       "myStruct is a struct for testing\n",
+			},
+		},
+	}
+
+	tt := []struct {
+		input              []byte
+		expectedResult     string
+		expectedErrorMatch string
+	}{
+		// valid queries
+		{input: []byte(`gno.land/r/hello`), expectedResult: expected.JSON()},
+		{input: []byte(`gno.land/r/doesnotexist`), expectedErrorMatch: `invalid package path`},
+	}
+
+	for _, tc := range tt {
+		name := string(tc.input)
+		t.Run(name, func(t *testing.T) {
+			env := setupTestEnv()
+			ctx := env.vmk.MakeGnoTransactionStore(env.ctx)
+			vmHandler := env.vmh
+
+			// Give "addr1" some gnots.
+			addr := crypto.AddressFromPreimage([]byte("addr1"))
+			acc := env.acck.NewAccountWithAddress(ctx, addr)
+			env.acck.SetAccount(ctx, acc)
+			env.bank.SetCoins(ctx, addr, std.MustParseCoins("10000000ugnot"))
+			assert.True(t, env.bank.GetCoins(ctx, addr).IsEqual(std.MustParseCoins("10000000ugnot")))
+
+			// Create test package.
+			files := []*gnovm.MemFile{
+				{Name: "hello.gno", Body: `
+// hello is a package for testing
+package hello
+
+// myStruct is a struct for testing
+type myStruct struct{a int}
+func (ms myStruct) Foo() string { return "myStruct.Foo" }
+// The prefix for the hello message
+const prefix = "Hello"
+func Hello(msg string) (res string) { res = prefix+" "+msg; return }
+`},
+			}
+			pkgPath := "gno.land/r/hello"
+			msg1 := NewMsgAddPackage(addr, pkgPath, files)
+			err := env.vmk.AddPackage(ctx, msg1)
+			assert.NoError(t, err)
+
+			req := abci.RequestQuery{
+				Path: "vm/qdoc",
+				Data: tc.input,
+			}
+
+			res := vmHandler.Query(env.ctx, req)
+			if tc.expectedErrorMatch == "" {
+				assert.True(t, res.IsOK(), "should not have error")
+				if tc.expectedResult != "" {
+					assert.Equal(t, tc.expectedResult, string(res.Data))
+				}
+			} else {
+				assert.False(t, res.IsOK(), "should have an error")
+				errmsg := res.Error.Error()
+				assert.Regexp(t, tc.expectedErrorMatch, errmsg)
+			}
+		})
+	}
+}

gno.land/pkg/sdk/vm/keeper.go

@@ -16,6 +16,7 @@
 	"time"
 
 	"github.com/gnolang/gno/gnovm"
+	"github.com/gnolang/gno/gnovm/pkg/doc"
 	gno "github.com/gnolang/gno/gnovm/pkg/gnolang"
 	"github.com/gnolang/gno/gnovm/stdlibs"
 	"github.com/gnolang/gno/tm2/pkg/crypto"
@@ -827,6 +828,22 @@
 	}
 }
 
+func (vm *VMKeeper) QueryDoc(ctx sdk.Context, pkgPath string) (*doc.JSONDocumentation, error) {
+	store := vm.newGnoTransactionStore(ctx) // throwaway (never committed)
+
+	memPkg := store.GetMemPackage(pkgPath)
+	if memPkg == nil {
+		err := ErrInvalidPkgPath(fmt.Sprintf(
+			"package not found: %s", pkgPath))
+		return nil, err
+	}
+	d, err := doc.NewDocumentableFromMemPkg(memPkg, true, "", "")
+	if err != nil {
+		return nil, err
+	}
+	return d.WriteJSONDocumentation()
+}
+
 // logTelemetry logs the VM processing telemetry
 func logTelemetry(
 	gasUsed int64,

gnovm/pkg/doc/doc.go

@@ -36,21 +36,14 @@ type WriteDocumentationOptions struct {
 }
 
 // Documentable is a package, symbol, or accessible which can be documented.
-type Documentable interface {
-	WriteDocumentation(w io.Writer, opts *WriteDocumentationOptions) error
-}
-
-// static implementation check
-var _ Documentable = (*documentable)(nil)
-
-type documentable struct {
+type Documentable struct {
 	bfsDir
 	symbol     string
 	accessible string
 	pkgData    *pkgData
 }
 
-func (d *documentable) WriteDocumentation(w io.Writer, o *WriteDocumentationOptions) error {
+func (d *Documentable) WriteDocumentation(w io.Writer, o *WriteDocumentationOptions) error {
 	if o == nil {
 		o = &WriteDocumentationOptions{}
 	}
@@ -110,7 +103,7 @@ func (d *documentable) WriteDocumentation(w io.Writer, o *WriteDocumentationOpti
 	return d.output(pp)
 }
 
-func (d *documentable) output(pp *pkgPrinter) (err error) {
+func (d *Documentable) output(pp *pkgPrinter) (err error) {
 	defer func() {
 		// handle the case of errFatal.
 		// this will have been generated by pkg.Fatalf, so get the error
@@ -163,7 +156,7 @@ var fpAbs = filepath.Abs
 // dirs specifies the gno system directories to scan which specify full import paths
 // in their directories, such as @/examples and @/gnovm/stdlibs; modDirs specifies
 // directories which contain a gno.mod file.
-func ResolveDocumentable(dirs, modDirs, args []string, unexported bool) (Documentable, error) {
+func ResolveDocumentable(dirs, modDirs, args []string, unexported bool) (*Documentable, error) {
 	d := newDirs(dirs, modDirs)
 
 	parsed, ok := parseArgs(args)
@@ -173,7 +166,7 @@ func ResolveDocumentable(dirs, modDirs, args []string, unexported bool) (Documen
 	return resolveDocumentable(d, parsed, unexported)
 }
 
-func resolveDocumentable(dirs *bfsDirs, parsed docArgs, unexported bool) (Documentable, error) {
+func resolveDocumentable(dirs *bfsDirs, parsed docArgs, unexported bool) (*Documentable, error) {
 	var candidates []bfsDir
 
 	// if we have a candidate package name, search dirs for a dir that matches it.
@@ -208,13 +201,13 @@ func resolveDocumentable(dirs *bfsDirs, parsed docArgs, unexported bool) (Docume
 	}
 	// we wanted documentation about a package, and we found one!
 	if parsed.sym == "" {
-		return &documentable{bfsDir: candidates[0]}, nil
+		return &Documentable{bfsDir: candidates[0]}, nil
 	}
 
 	// we also have a symbol, and maybe accessible.
 	// search for the symbol through the candidates
 
-	doc := &documentable{
+	doc := &Documentable{
 		symbol:     parsed.sym,
 		accessible: parsed.acc,
 	}
@@ -246,7 +239,7 @@ func resolveDocumentable(dirs *bfsDirs, parsed docArgs, unexported bool) (Docume
 			}
 			doc.bfsDir = candidate
 			doc.pkgData = pd
-			// match found. return this as documentable.
+			// match found. return this as Documentable.
 			return doc, multierr.Combine(errs...)
 		}
 	}