bug#25461: [Patch]: Missing doc strings for "," and ",@".

[Alan Mackenzie]

Hello, Michael.

On Sat, Jan 21, 2017 at 03:26:06 +0100, Michael Heerdegen wrote:
> Hello Alan,

[ .... ]

> I don't want that we change the docs to the worse.

I somehow don't think you'll be happy with any modifications I make to
the proposed doc strings which leaves their basic structure unchanged.

How about starting on a different tack.  Would you accept , and ,@
having doc strings, with the entirety of these being:

[for ,]:
    See ``' (and also `pcase') for the details of `,'.

[for ,@]:
    See ``' for the details of `,@'.

?

[ .... ]

> It [ , ] is implicitly given a meaning by the implementation of "`".
> That's why it's documented in the documentation of "`".  For the same
> reason that there is no separate documentation for :group just because
> it has a meaning in defcustom, or there is no mentioning in the
> docstring that the symbol `error' has a different meaning as car of a
> list that is an error handler in condition-case, or that car has a
> different meaning in (setf (car something) ...) or...

> All these examples appear in symbolic expressions (i.e. lists) that are
> not evaluated normally.  Like in the tiny example above.  If we try to
> mention what a symbol potentially could mean in any sexp that is not
> evaluated normally in this symbol's docstring, our documentation would
> become very messy, because lists that are not evaluated normally are
> very common in Lisp.  That's why we normally collect this information in
> the documentation of the functions/macros that implement this meaning.
> This is not a problem because it's easy to look at the context and
> consult the documentation of the surrounding form.

, and ,@ are different: it is not obvious to the unexperienced what
"sexp" they belong to in something like

    `(if ,cond (progn ,@body))

.  How is a beginner supposed to connect up the ,@ in that example with
the ` which doesn't directly enclose or otherwise connect with it?

[ .... ]

(I'll address your points that I've snipped if they become relevant
again.)

> Regards,

> Michael.

-- 
Alan Mackenzie (Nuremberg, Germany).