GNU bug report logs - #48779
(:documentation mydoc) not working

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 48779 in the body.
You can then email your comments to 48779 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Christopher Dimech <dimech <at> gmx.com>
To: bug-gnu-emacs <at> gnu.org
Subject: (:documentation mydoc) not working
Date: Tue, 1 Jun 2021 17:23:12 +0200

I have the code below.  Doing "C-h f aoe" gives

-------- help ---------

aoe is a Lisp function in ‘gungadin.el’.

(aoe X)

Not documented.


-------- code --------

(defvar mydoc "foobar")

(defun aoe (x)
  (:documentation mydoc)
  (+ x 42))

-------- code --------



----- Christopher Dimech

Society has became too quick to pass judgement and declare someone Persona Non-Grata, 
the most extreme form of censure a country can bestow. 

In a new era of destructive authoritarianism, I support Richard Stallman.  Times of great 
crisis are also times of great opportunity. I call upon you to make this struggle yours as well !

https://stallmansupport.org/     https://www.fsf.org/     https://www.gnu.org/

Message #8 received at 48779 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Christopher Dimech <dimech <at> gmx.com>
Cc: 48779 <at> debbugs.gnu.org
Subject: Re: bug#48779: (:documentation mydoc) not working
Date: Tue, 01 Jun 2021 17:33:23 +0200

Christopher Dimech <dimech <at> gmx.com> writes:

> I have the code below.  Doing "C-h f aoe" gives
>
> -------- help ---------
>
> aoe is a Lisp function in ‘gungadin.el’.
>
> (aoe X)
>
> Not documented.
>
> -------- code --------
>
> (defvar mydoc "foobar")
>
> (defun aoe (x)
>   (:documentation mydoc)
>   (+ x 42))

This undocumented feature only works in lexical-binding buffers.

And there's no need to post bug reports about things you're wondering
about, especially when you're also discussing this on other Emacs
mailing lists.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #15 received at 48779 <at> debbugs.gnu.org (full text, mbox):

From: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Christopher Dimech <dimech <at> gmx.com>
Cc: "48779 <at> debbugs.gnu.org" <48779 <at> debbugs.gnu.org>
Subject: RE: [External] : bug#48779: (:documentation mydoc) not working
Date: Tue, 1 Jun 2021 15:47:07 +0000

> This undocumented feature only works in lexical-binding buffers.

My questions here would be:

1. Why is it undocumented?
2. Why does it work only for lexical-binding buffers?

___

:documentation is documented in the Elisp manual,
but only for `cl-defgeneric'.

(Grepping the Lisp source code shows there are :doc,
:doc-spec, and :documentation.  :doc is documented
in the Elisp manual, in the context of defcustom.
:doc-spec seems to be documented in no manual.)

We don't document everything, of course.  But should
:documentation be documented for defun, as well as
for cl-defgeneric?

Yes, the latter is an emulation of Common Lisp's
`defgeneric', which has :documentation.  But defun
also has it now, apparently.

Message #18 received at 48779 <at> debbugs.gnu.org (full text, mbox):

From: Christopher Dimech <dimech <at> gmx.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 48779 <at> debbugs.gnu.org
Subject: bug#48779: (:documentation mydoc) not working
Date: Tue, 1 Jun 2021 23:13:23 +0200

> Sent: Wednesday, June 02, 2021 at 3:33 AM
> From: "Lars Ingebrigtsen" <larsi <at> gnus.org>
> To: "Christopher Dimech" <dimech <at> gmx.com>
> Cc: 48779 <at> debbugs.gnu.org
> Subject: bug#48779: (:documentation mydoc) not working
>
> Christopher Dimech <dimech <at> gmx.com> writes:
> 
> > I have the code below.  Doing "C-h f aoe" gives
> >
> > -------- help ---------
> >
> > aoe is a Lisp function in ‘gungadin.el’.
> >
> > (aoe X)
> >
> > Not documented.
> >
> > -------- code --------
> >
> > (defvar mydoc "foobar")
> >
> > (defun aoe (x)
> >   (:documentation mydoc)
> >   (+ x 42))
> 
> This undocumented feature only works in lexical-binding buffers.
> 
> And there's no need to post bug reports about things you're wondering
> about, especially when you're also discussing this on other Emacs
> mailing lists.

I put it as it did seem a difficult problem that still remains unsolved.
 
> -- 
> (domestic pets only, the antidote for overdose, milk.)
>    bloggy blog: http://lars.ingebrigtsen.no
> 
> 
> 
>

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.