bug#48779: (:documentation mydoc) not working

bug#48779: (:documentation mydoc) not working

[Christopher Dimech]

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/

bug#48779: (:documentation mydoc) not working

[Lars Ingebrigtsen]

Christopher Dimech <dimech@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

bug#48779: [External] : bug#48779: (:documentation mydoc) not working

[Drew Adams]

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

bug#48779: (:documentation mydoc) not working

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 3:33 AM
> From: "Lars Ingebrigtsen" <larsi@gnus.org>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: 48779@debbugs.gnu.org
> Subject: bug#48779: (:documentation mydoc) not working
>
> Christopher Dimech <dimech@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
> 
> 
> 
>