x/tools/godoc: misleading documentation rendering for mix of exported and unexported iota consts

[lukatendai]

If you look at documentation on this page: https://golang.org/pkg/text/template/parse/#NodeType

The NodeDot is 6 and NodeField is 8, but there is nothing between these two constants. however the source has two unexported consts between NodeDot and NodeField, which makes NodeField 8.

When you debug the code you can easly misunderstand the node types but simply counting them from the top.

The documentation should indicate actual values of constants

[dmitshur]

Thanks for reporting.

Such constant blocks are not very common, but they should still be displayed in a way that isn't potentially misleading.

A workaround that exists for now is to use the ?m=all mode to display all identifiers:

https://golang.org/pkg/text/template/parse/?m=all#NodeType

We can consider inserting a comment in place of the hidden unexported identifiers along the lines of "// contains filtered or unexported fields":

const (
    NodeText    NodeType = iota // Plain text.
    NodeAction                  // A non-control action such as a field evaluation.
    NodeBool                    // A boolean constant.
    NodeChain                   // A sequence of field accesses.
    NodeCommand                 // An element of a pipeline.
    NodeDot                     // The cursor, dot.
    // contains filtered or unexported fields
    NodeField      // A field or method name.
    NodeIdentifier // An identifier; always a function name.
    NodeIf         // An if action.
    NodeList       // A list of Nodes.
    NodeNil        // An untyped nil constant.
    NodeNumber     // A numerical constant.
    NodePipe       // A pipeline of commands.
    NodeRange      // A range action.
    NodeString     // A string constant.
    NodeTemplate   // A template invocation action.
    NodeVariable   // A $ variable.
    NodeWith       // A with action.
)

Or perhaps there's an even better way to resolve this issue.

/cc @griesemer

[lukatendai]

I wonder if we can recognize that situation and simply add the note that there are unexported fields and add the link to switch to m=all

[griesemer]

@lukatendai 's suggestion seems good.