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
proposal: cmd/godoc: add quotation support to express arguments and global variables #21902
Comments
This kind of feature has different names in programming environments.
In many GNU projects backquote plus quote is used. Like `p'. // F has `aa' and `bb' parameters.
func F(aa, bb int) Emacs Lisp uses ALL_UPPER for param names in docstring. // F has AA and BB parameters.
func F(aa, bb int) doxygen uses // F has \p aa and \p bb parameters.
func F(aa, bb int) I believe Javadoc uses something like // F has {@param aa} and {@param bb} parameters.
func F(aa, bb int) KDoc (Kotlin) has inline markup. In particular, it specifies element links. // F has [aa] and [bb] parameters.
func F(aa, bb int) In natural languages, we also use quotation to express "literal" entities. // F has "aa" and "bb" parameters.
func F(aa, bb int) |
"Golang often uses small variable names (e.g. a, s)" - maybe makes sense simply to stop using awful names instead of making it easier...? |
@namusyaka, I think you should work on the wording. |
Personally, I have a temptation to identify a parameter name inside documentation comment, but since Go does not have any conventions for it, I resist that. СС @TocarIP. |
I'm usually 100% opposed to any addition to the not-markup recognized by godoc but this one is tempting. It can be awkward to balance the name of the parameter (short or not) with a natural language description of its use. I tend to leave it unadorned if clear from context or use single or double quotes. It works but can be inaesthetic at times. However, if this proposal got accepted, what would the effect be other than settling on a particular convention? Would godoc display the variables differently? Would it do something other than just display them differently? The only thing I can think of would be to display them in the same style as an indented block. In that case, maybe this is more generally just a means to have inline code formatting? (In html terms, a That seems like a useful generalization that would also satisfy this issue. For example the docs on math.Hypot could be displayed as: Hypot returns |
What is this proposal trying to solve? It provides some pretty printing to variable names, but global variables almost always BeginWithUpperCase, so identifying them in prose is fairly easy. As for local variables, you would only be referring to variables from the function or method you are documenting, so the context should make it clear what you are referring to. |
@quasilyte @dkolistr Thanks for pointing that out. I've edited the words. If I don't understand things correctly, please let me know.
I affirm the coding style of using short variable names, but I concerned to conflict the short variable name and the words that existing in the natural language. |
In the example case, "The an argument is not modified." is a poor sentence and hard to parse. It could have been worded as "The account is not modified.". |
We're not going to accept writing anything along the lines of Simply quoting parameter names seems at least conceivable. CC @robpike |
I like this. |
@rakyll As a separated issue, I have sent a CL for reflecting your revirew. Could you take a look at that? |
It requires no change at all in godoc to use a sentence with a confusing variable name such as "a". Any comment about "a" can be made easy to understand by just quoting "a", like this. In other words, instead of changing godoc, just use punctuation. |
I agree to use the punctuation for improving ease of reading docs. |
What clarification are you asking about? |
@robpike For example, it is to add a reference to effective go such as "Use puncutation when referring arguments in functions and method comments". |
There are hooks in godoc to apply a formatting filter to arguments automatically. If the presentation of argument names is important, we should investigate applying that automatic filtering instead of introducing new syntax that everyone must learn. I've certainly renamed arguments to avoid confusion with the same English word in documentation, but I think that's a net win no matter what. Even if there are font differences, seeing something like "If |
Overview
We often prefer to use short variable names (e.g.
a
,s
) when programming with Golang, but due to it, it may conflict with actual words in godoc, as my stupid mistake is: https://go-review.googlesource.com/c/crypto/+/63991So, I'd like to support the feature as titled for function or method comments.
Proposal approach
As Iskander says in the CL, use `` or @ to express that variable or argument. (e.g.
@a
)Of course, for me, that grammar is not important, I hope to eliminate the above mistakes beforehand.
What do you think about this?
I've confirmed whether this proposal has already been done, but I'm sorry if it was duplicated.
/cc @quasilyte
The text was updated successfully, but these errors were encountered: