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
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@lukatendai
Copy link

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
@ianlancetaylor ianlancetaylor added help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels 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
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label May 18, 2020
@dmitshur
Copy link
Contributor

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

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

@lukatendai 's suggestion seems good.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation help wanted NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

5 participants