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

[Alan Mackenzie <acm@muc.de>]

Hello, Michael.

On Fri, Jan 20, 2017 at 00:12:18 UTC, Michael Heerdegen wrote:
> Alan Mackenzie <acm@muc.de> writes:

> > > > +;; Give `,' and `,@' documentation strings which can be examined by C-h f.
> > > > +(put '\, 'function-documentation
> > > > +     "`,' signals that the next form should be evaluated and inserted.
> > > > +It can occur only in `\\=`' constructs.
> > > > +
> > > > +For example:
> > > > +
> > > > +b              => (ba bb bc)		; assume b has this value
> > > > +\\=`(a ,b c)      => (a (ba bb bc) c)	; insert the value of b
> > > > +
> > > > +See also `\\=`' and `,@'.

> > > I don't think this makes it easier for people to understand things.
> > > This suggests that "," has some kind of meaning per se, that it is a
> > > macro-like thing, etc, and that pcase somehow redefines it.

> > Yes.  All these things are true, aren't they?

> That `,' "signals" something is too vague to be true or false.  As an
> explanation of things, I don't find it good, and in the generality that
> this sentence is speaking, I would say it's wrong.

OK, I'll accept that.  I can't see where it's wrong, though.  I've
changed it to say "causes" rather than "signal".  (See below.)

> That "," can only appear inside "`" is simply wrong.

That's poor wording on my part.  What I really meant was that for , to
have the effect described, it must be in a ` construct.  I've amended
this bit too (see below).

[ .... ]

> It is also not the case that `pcase' redefines "`".

pcase causes ` to be expanded by the macro \`--pcase-macroexpander in
place of the macro \`.  What is that if it is not pcase redefining `?

> And yes, I've seen uses of "," outside of "`" in Lisp.  And it's
> perfectly fine to use "," for anything anyone wants - like any other
> symbol.

I disagree with you, here.  Using standard Elisp symbols to mean
something different is a recipe for confusion.  I don't think it is in
any way fine to use `if', `and', `car', .... for non standard purposes.
I also don't think it's OK to do the same with ` or ,.

> You don't seem to be confused by the fact that `rx' "(re-)uses" `and',
> `or' etc.  What makes "`" different?  The fact that it is a "reader
> macro"?

I wasn't aware of rx.  I don't think it was good to reuse `and' the way
it does, but (subjectively) I don't think it will have caused all that
much confusion.

> > > Of course there is a logic behind pcase's usage of ` and ,.  The
> > > usage of these suggests a mental model for their "meaning".  But we
> > > should not describe our mental models in docstrings.  That's only
> > > useful for people sharing the same model.

> > I'm not sure I'm following you here.  A high level description of a
> > function necessarily involves a mental model.

> Maybe.  But you are describing properties of your mental model instead
> of properties of the language.  Your mental model led you to confusion
> and wrong conclusions.

I disagree with you, here.  I'm describing the simple straighforward
normal effect of ,.  I don't understand why you're making such a big
deal out of it.

> It's not optimal to describe these things.  It will confuse others.

I disagree with you here, too.  , and ,@ have a simply stated meaning in
the typical case, far simpler than you're making it out to be.

> > ` has a specific meaning, and has had a high quality doc string for
> > ever.

> Because it has a `symbol-function'.

> > , likewise has a specific meaning,

> That's one part that led you to confusion.

> > but doesn't yet have a doc string.

> ... because it is undefined.

It is defined.  I intend that definition to be in a doc string.

> > > So I think we maximally should describe what the reader does with `
> > > etc., so that people know what to search for in the manual or remember
> > > what they already had learned.

> > We don't do that for other functions.  A function's doc string should be
> > a crisp summary of what a function _does_.  A doc string which directs
> > people to a manual, or is so confusing or unspecific that the reader is
> > forced to open a manual, is a failed doc string.

> But that's exactly the point: "," is not a function or a macro.

No, but it needs a doc string.

> So how it is used is arbitrary.

If that were the case, Emacs wouldn't even build.  ,'s use is no more
arbitrary than any other symbol in Lisp.

> It's traditionally used by "`", but it's not restricted to that.
> There may be even more use cases in future Elisp.  And that is good.

I disagree with that last sentiment.

> > , has a definite precise function (disregarding its use in pcase for
> > now).  Have you any specific suggestions on how to improve my wording of
> > its doc string?

> > > +		 ((get function 'reader-macro)
> > > +                  "a reader macro")

> > > We don't have reader macros in Emacs.

> > The reader performs macro-like actions.  What is the correct alternative
> > term for what the reader does with ', `, ,, #', etc.?

> The manual seems to prefer the term "reader syntax".  I think we could
> use this term.

No, that won't do.  , has semantics as well as syntax.

> You can say that the reader expands `X to (` X), and that "`" is a
> defined macro.  You can say that the reader expands ,X to (\, X), and
> that a frequent usage is in backquote forms.

That is describing the internal mechanism of , rather than the result.
It would be utterly useless and confusing for the people who need to
consult the meaning of , and ,@, namely new Elisp hackers.

> We should not say that "," "does" something, because this makes no
> sense and leads a person reading this to false assumptions.

It will enable them to understand code they are reading, and to start
writing ` constructs themselves.

Here is the latest proposed version of the doc string for ,,
incorporating some of the comments you've made.


        "`,' causes the next form to be evaluated and inserted.
    It occurs in `\\=`' constructs.

    For example:

    b              => (ba bb bc)            ; assume b has this value
    \\=`(a ,b c)      => (a (ba bb bc) c)   ; insert the value of b

    See also `\\=`' and `,@'.

    (Note that ``' constructs (including `,'s) sometimes have different
    semantics.  This occurs, for example, with the macro `pcase' and other
    macros with similar names.")
 

> Regards,

> Michael.

-- 
Alan Mackenzie (Nuremberg, Germany).