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

[Alan Mackenzie <acm@muc.de>]

Hello, Noam.

On Wed, Jan 18, 2017 at 07:16:34PM -0500, npostavs@users.sourceforge.net wrote:
> Alan Mackenzie <acm@muc.de> writes:


> > I'll just point out one thing I'm proposing changing.  That is, to use
> > princ rather than prin1 to print the name of the function.  This causes,
> > for example, backtick to be printed as

> >     `

> > rather than the

> >     \`

> > we get at the moment.  This might cause problems for function names
> > which include backslashes or unprintable characters such as \n.

> Perhaps only do this for symbols which have `reader-macro' set in their
> plist?

That sounds like a good idea.

> > +;; 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.

> This conflates the reader macro with its particular use by the backquote
> macro.  

The use by backquote isn't "a particular" use, as though there were
several equally valid uses.  This use is the prime one, and up until
fairly recently the only one.  Other uses are subsidiary (and I make
reference to the other one lower down).

> I think it's better to explain only the reader macro here, and
> link to ` and pcase for more details.

In other words, omit the semantics from the doc string.  I don't think
that's a good idea: "This macro transforms `foo' into ....., but you'll
have to look up ..... to see what it actually does.".  We don't do that
for macros like `when' and `unless', or any others I can think of, so
why do it for ,?

> > +It can occur only in `\\=`' constructs.

> This isn't true.

In what sense is it not true?  I've never seen a comma used otherwise in
a lisp program.  What misunderstanding could it cause in a (relatively
new) Lisp hacker reading it?  I realise that it is possible to write
(defun \, (...) ...), but that is surely of interest only to people
testing Emacs.

-- 
Alan Mackenzie (Nuremberg, Germany).