Go: proposal: cmd/godoc: add quotation support to express arguments and global variables

[namusyaka]

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/+/63991
So, 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

[quasilyte]

This kind of feature has different names in programming environments.
I will try to enumerate some existing conventions to:

1. To emphasize that this feature is not alien to many of us. It is considered useful not only for tools, but more importantly, for us, humans.
2. To make it easier to understand what exactly this ticket tries to discuss.

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 command escapes, one of them is \p which is used for parameters.

// F has \p aa and \p bb parameters.
func F(aa, bb int)

I believe Javadoc uses something like {@param X}.
PHPDoc does the same thing: inline tags.

// 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)

[dkolistratova]

"Golang often uses small variable names (e.g. a, s)" - maybe makes sense simply to stop using awful names instead of making it easier...?

[quasilyte]

@namusyaka, I think you should work on the wording.

[quasilyte]

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.
This may be a habit from my previous programming experience combined with subjective preferences.

СС @TocarIP.

[jimmyfrasche]

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 code/kbd tag vs. a pre tag).

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 Sqrt(p*p + q*q), taking care to avoid unnecessary overflow and underflow.

[dsnet]

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.

[namusyaka]

@Quasilyte @dkolistr Thanks for pointing that out. I've edited the words. If I don't understand things correctly, please let me know.

@dsnet

What is this proposal trying to solve?

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.
Therefore, I would like to make them visible (and logically in HTML) distinguishable by using specific grammar within comment, even if that conflict occurs.

[rakyll]

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.".

[ianlancetaylor]

We're not going to accept writing anything along the lines of @a. That kind of proposal has been made before and has been consistently rejected.

Simply quoting parameter names seems at least conceivable.

CC @robpike

[namusyaka]

Simply quoting parameter names seems at least conceivable.

I like this.

[namusyaka]

@rakyll As a separated issue, I have sent a CL for reflecting your revirew. Could you take a look at that?

[robpike]

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.

[namusyaka]

I agree to use the punctuation for improving ease of reading docs.
By the way, is it possible to clarify the rule on the variable name inside function/method comment?

[robpike]

What clarification are you asking about?

[namusyaka]

@robpike For example, it is to add a reference to effective go such as "Use puncutation when referring arguments in functions and method comments".

[rsc]

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 a is null" is much less clear than (say) "If x is null". So prefer x, y over a, b regardless.