Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
lukatendai opened this issue May 15, 2020 · 3 comments

Comments

@lukatendai
Copy link

@lukatendai lukatendai commented May 15, 2020

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

@ianlancetaylor ianlancetaylor changed the title Documentation problem with mix of exported and unexported iota consts cmd/godoc: documentation problem with mix of exported and unexported iota consts May 15, 2020
@ianlancetaylor ianlancetaylor added this to the Backlog milestone May 15, 2020
@dmitshur dmitshur changed the title cmd/godoc: documentation problem with mix of exported and unexported iota consts x/tools/godoc: misleading documentation rendering for mix of exported and unexported iota consts May 18, 2020
@dmitshur
Copy link
Contributor

@dmitshur dmitshur commented May 18, 2020

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
Copy link
Author

@lukatendai lukatendai commented May 18, 2020

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
Copy link
Contributor

@griesemer griesemer commented May 18, 2020

@lukatendai 's suggestion seems good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
5 participants