@pierre-rouleau

The change is valid, however I would have replaced num buy _num. A symbol that starts with an underscore is ignore and can be used as a reminder of the meaning. That's useful for documentation and would help if one day the num value is indeed required.

Fair enough, done.

I don't think the `quote-style' is valid in this case, as it is normally used for creating 'elisp hyperlinks' inside the viewed docstring to the elisp variable or function.

I usually view the style as an analog to inline-code in markdown, with the benefit that it may create a hyperlink if the value refers to existing function/variable. AFAIU there's no other way to represent "inline code".

To resolve the question I went to see what Emacs manual says. This section describes the style behavior. It doesn't directly describe our situation, but it has this sentence:

If a symbol has a function definition and/or a variable definition, but those are irrelevant to the use of the symbol that you are documenting, you can write the words ‘symbol’ or ‘program’ before the symbol name to prevent making any hyperlink. For example […]

The point of styling the symbol in such way but avoiding hyperlink creation is only the visual appearance, i.e. using the style as inline-code.

So I think the change is valid.

@Hi-Angel

To resolve the question I went to see what Emacs manual says. This section describes the style behavior. It doesn't directly describe our situation, but it has this sentence:

If a symbol has a function definition and/or a variable definition, but those are irrelevant to the use of the symbol that you are documenting, you can write the words ‘symbol’ or ‘program’ before the symbol name to prevent making any hyperlink. For example […]

The point of styling the symbol in such way but avoiding hyperlink creation is only the visual appearance, i.e. using the style as inline-code.

So I think the change is valid.

After re-reading the Emacs manual I would have to agree. However when I wrote `list' or `error' inside one of my docstrings, the help buffer rendering that docstring did create a link to list and error primitive emacs functions and they were not following the word 'function' inside the docstring. I tested that with Emacs 30.2. Creating such links is certainly not the intent of the docstring in these elsip functions for go.

Did you check that `error' did not create a link with to the error emacs lisp native function in your environment after byte-compiling your code? If not, I wonder if there is something else controlling that.

Oh yeah, you're right. I see error among my changes and it's interesting that if I quote it with \\=', it still creates a link. So I ended up just using double quotes.

I am curious: What was the exact docstring text and quoting with the \\=' around error that still created a link?

I am curious: What was the exact docstring text and quoting with the \\=' around error that still created a link?

Well, for example upon evaluating this code:

(defun foo ()
  "\\='error'"
  t)

…and then invoking help for foo I get *Help* buffer with error being a link. Reproducible with emacs -Q.

It may be a bug in my Emacs version though — I am using Emacs built from master on 3 June, that's 4 months ago.

I have the same behaviour on Emacs 30.2 that I built from source. I also tried it in Emacs 26.3 and it does the same.

I also wonder if this is the expected behaviour. I'll ask on Emacs mailing list.

Is this (still) ready to merge?

Yeah, review comments have been addressed. @pierre-rouleau is discussing the error auto-link situation with upstream, but it's just one line and I worked it around by simply using double-quotes.

Important note: as PR description says, it fixes most of the warnings, but not all of them. I just fixed the low-hanging fruit back when I opened the PR.

@dominikh As far as I am concerned, the changes are fine.

As for the docstring markup, I will (later this week probably), go through Emacs documentation and extract what I understand, ask specific questions to the Emacs devs and if I see problems will try to identify them clearly to them.