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.

Sign up for GitHub

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

Jump to bottom

go/types: some small problems in docs #35189

Closed
yaxinlx opened this issue Oct 26, 2019 · 5 comments
Closed

go/types: some small problems in docs #35189

yaxinlx opened this issue Oct 26, 2019 · 5 comments
Labels
Documentation ExpertNeeded FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.

Comments

@yaxinlx
Copy link

yaxinlx commented Oct 26, 2019 •
edited by dmitshur

In the docs of the selections:

Selector    Kind          Recv    Obj    Type               Index     Indirect

p.x         FieldVal      T       x      int                {0}       true
p.m         MethodVal     *T      m      func (e *T) m()    {1, 0}    true
T.m         MethodExpr    T       m      func m(_ T)        {1, 0}    fals

Should the Type columns for the second and third line be func() and func(_ T)?
@yaxinlx
Copy link
Author

yaxinlx commented Oct 27, 2019 •
edited by dmitshur

And in the func (*Scope) LookupParent docs:

...  (see Insert, below) ...

The Insert method docs is shown above the LookupParent docs in fact.

@yaxinlx yaxinlx changed the title go/types: types of selections go/types: some small problems in docs Oct 27, 2019
@dmitshur dmitshur added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Oct 29, 2019
@dmitshur
Copy link
Contributor

The Insert method docs is shown above the LookupParent docs in fact.

It's below in source code, but above in documentation (since godoc displays identifiers in alphabetical order). We can fix this by making it say just "see Insert"; the reader should be able to find Insert easily in either medium.

@dmitshur
Copy link
Contributor

dmitshur commented Oct 29, 2019 •
edited

Should the Type columns for the second and third line be func() and func(_ T)?

That does seem more fitting to me too. It's also what https://github.com/golang/example/tree/master/gotypes#selections uses. The current text seems to be close to what types.SelectionString may produce, but that is the string form of the entire selector expression, not just its type. (Relevant playground snippet here.)

@griesemer Do you agree it would be an improvement, or are we missing some context?

/cc @dominikh

@dmitshur dmitshur added ExpertNeeded NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Oct 29, 2019
@griesemer
Copy link
Contributor

Agreed. CL forthcoming.

@dmitshur dmitshur added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels Oct 29, 2019
@gopherbot
Copy link

Change https://golang.org/cl/204044 mentions this issue: go/types: clarify documentation

@golang golang locked and limited conversation to collaborators Oct 28, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation ExpertNeeded FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@dmitshur @griesemer @gopherbot @yaxinlx