proposal: go/doc: consts/vars should be grouped with types by their computed type

[willfaught]

Currently, constant and variable declarations must have an explicit type to be grouped with that type. For example, go/build.Context is declared like var Default Context = defaultContext(), with an explicit Context type, because otherwise Default wouldn't be listed under the Context type.

If you add an explicit type, and the type can be inferred from the right-hand side of the assignment, then golint complains about the redundant explicit type.

If the Context type was missing from the Default declaration, it would be impossible to know for sure what type it is, since defaultContext isn't exported. (Okay, maybe you could guess in this situation, but what if it was called getDefault instead?)

We should instead compute a const/var declaration's type with the type checker and group them in doc accordingly.

[mvdan]

This makes sense, but I wonder if the restriction was made on purpose so that the doc family of programs didn't need to run the type-checker.

Perhaps this is more attainable now that better caching is in place. vet now requires type information at all times, for example.

[dsnet]

The grouping is performed by the go/doc package. As @mvdan mentioned, I'm pretty sure the reason is because doc.New which takes in an ast.Package lacks the type information needed to infer what the type of the variable is. It's not clear to me how to resolve this. You could derive a limited amount of type information from the ast.Package alone, but I'm not sure the complexity of that logic is worth it.

\cc @griesemer

[griesemer]

What @mvdan and @dsnet said. go/doc doesn't have exact type information and uses heuristics. For variables and constants that don't have an explicit (or named) type in the declaration, the type would have to be inferred from the initialization expressions which is non-trivial.

With respect to any "decisions being made", note that go/doc is one of the earliest Go packages around (just after go/ast), years before go/types came into being. It was always meant to be working on source code alone (so that it would work with partial packages or missing import information).

Now, with go/types being available, one could do a much better job when all information is present, and gracefully degrade to heuristics when information is missing.

The suggestion is reasonable, not sure it needs to be a proposal. If somebody wants to pick this up and do the actual work, I'd be ok with it. Note that changes to go/doc's API need to be backward compatible to satisfy the Go 1 guarantee. Also, all consumers of go/doc need to be adjusted accordingly. It's a lot of work.

Finally, and perhaps most importantly, there need to be decisions as to what to group where exactly, and what to do when type information is missing.

[willfaught]

@griesemer When should an issue be a proposal? I'd assumed it was for non-bug/enhancement issues.

[griesemer]

@willfaught I just re-read the proposal requirements and you're correct, this suggestion meets the requirements for a proposal.

[jimmyfrasche]

There would need to be two changes to the go/doc api.

A new Package constructor:

package doc
//use typs instead of heuristics for grouping
func NewTyped(pkg *ast.Package, typs *types.Package, importPath string, mode Mode) *Package

And a means to handle type aliases. Maybe an Aliases []*ast.GenDecl on doc.Type?

However, since this is to support the godoc/go doc commands the real hard part is getting the type information into them. The godoc vfs caused some issues when I tried it ( #20131 (comment) ) and when run locally you'd want access to the go tools's cache, but godoc isn't part of the go tool so it's unclear to me how that would work (though I haven't really looked at any of the caching code).

[rsc]

As @griesemer said above, this would require type information inside go/doc (and therefore available to cmd/doc, etc). That has not been an assumption before, and it would significantly complicate cmd/doc's file system scans.

[rsc]

I didn't mean to close this - wrong button. But probably we can't do this - leaving open for more discussion.

[willfaught]

Wouldn't doc.New be able to construct a types.Package from its pkg parameter?

doc.New:

func New(pkg *ast.Package, importPath string, mode Mode) *Package

types.Config.Check:

func (conf *Config) Check(path string, fset *token.FileSet, files []*ast.File, info *Info) (*Package, error)

For example:

// doc.New
func New(pkg *ast.Package, importPath string, mode Mode) *Package {
    var c = &types.Config{
        DisableUnusedImportCheck: true,
        IgnoreFuncBodies: true,
        Importer: importer.Default(),
    }

    var files []*ast.File

    for _, f := range pkg.Files {
        files = append(files, f)
    }

    var tp *types.Package

    if p, err := c.Check(importPath, token.NewFileSet(), files); err == nil && p.Complete() {
        tp = p
    }

    // ...
}

---

@jimmyfrasche What's godoc vfs?

[griesemer]

@willfaught There's no question that go/doc could type-check packages. But it is also supposed to work with incomplete packages (at least that's one of the original intents). The devil is in the details.