Prefix Argument and optional argument

Prefix Argument and optional argument

[carlmarcos--- via Users list for the GNU Emacs text editor]

I am having difficulty figuring out any problems associated with the following two functions.

Can one safely call "M-x name", "C-u M-x name", "C-u 2 M-x name", where name is either
`poke' or `poke-opt'.

(defun poke (prefix)
  "TODO."
  (interactive "P")
...)

(defun poke-opt (&optional prefix)
  "TODO."
  (interactive "P")
...)

Re: Prefix Argument and optional argument

[Bruno Barbier]

carlmarcos--- via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> I am having difficulty figuring out any problems associated with the following two functions.
>
> Can one safely call "M-x name", "C-u M-x name", "C-u 2 M-x name", where name is either
> `poke' or `poke-opt'.
>
> (defun poke (prefix)
>   "TODO."
>   (interactive "P")
> ...)

You should compile your code; Emacs will say:

    Warning: misplaced interactive spec: ‘(interactive P)’


>
> (defun poke-opt (&optional prefix)
>   "TODO."
>   (interactive "P")
> ...)

This version is OK. You can call it "M-x name", "C-u M-x name", "C-u 2
M-x name"; wether it's safe or not depends on its body though ;-)

Bruno

Re: Prefix Argument and optional argument

[Michael Heerdegen]

carlmarcos--- via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> Can one safely call "M-x name", "C-u M-x name", "C-u 2 M-x name",
> where name is either `poke' or `poke-opt'.

If you really try, maybe better wear a mask.

Michael.

Re: Prefix Argument and optional argument

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 5, 2022, 06:52 by brubar.cs@gmail.com:

> carlmarcos--- via Users list for the GNU Emacs text editor
> <help-gnu-emacs@gnu.org> writes:
>
>> I am having difficulty figuring out any problems associated with the following two functions.
>>
>> Can one safely call "M-x name", "C-u M-x name", "C-u 2 M-x name", where name is either
>> `poke' or `poke-opt'.
>>
>> (defun poke (prefix)
>>   "TODO."
>>   (interactive "P")
>> ...)
>>
>
> You should compile your code; Emacs will say:
>
>  Warning: misplaced interactive spec: ‘(interactive P)’
>

I did call `M-x byte-compile-file file' but did not get the warning you desrcibe.


>>
>> (defun poke-opt (&optional prefix)
>>   "TODO."
>>   (interactive "P")
>> ...)
>>
>
> This version is OK. You can call it "M-x name", "C-u M-x name", "C-u 2
> M-x name"; wether it's safe or not depends on its body though ;-)
>
> Bruno
>

Have done as follows

(defun poke (&optional prefix)
  "TODO"
  (interactive "P")

  (cond
   ((equal current-prefix-arg nil)   ; no C-u
    (setq poke-name-mode 1))

   ((equal current-prefix-arg '(4))  ; C-u
    (setq poke-name-mode 0)
    (arktika-workbench))

   ((equal current-prefix-arg 1)     ; C-u 1
    (setq poke-name-mode 0)

    (let* ( (name (read-from-minibuffer " Name: ")) )
      (arktika-workbench name))) ) ))

Re: Prefix Argument and optional argument

[Michael Heerdegen]

carlmarcos--- via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> > You should compile your code; Emacs will say:
> >
> >  Warning: misplaced interactive spec: ‘(interactive P)’
> >
>
> I did call `M-x byte-compile-file file' but did not get the warning
> you desrcibe.

This has been added to master only recently.

Michael.

Re: Prefix Argument and optional argument

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 5, 2022, 20:26 by help-gnu-emacs@gnu.org:

> Jul 5, 2022, 06:52 by brubar.cs@gmail.com:
>
>> carlmarcos--- via Users list for the GNU Emacs text editor
>> <help-gnu-emacs@gnu.org> writes:
>>
>>> I am having difficulty figuring out any problems associated with the following two functions.
>>>
>>> Can one safely call "M-x name", "C-u M-x name", "C-u 2 M-x name", where name is either
>>> `poke' or `poke-opt'.
>>>
>>> (defun poke (prefix)
>>>   "TODO."
>>>   (interactive "P")
>>> ...)
>>>
>>
>> You should compile your code; Emacs will say:
>>
>>  Warning: misplaced interactive spec: ‘(interactive P)’
>>
Why is it that a warning is shown, what is the problem with it.  Why should it only be optional?


> I did call `M-x byte-compile-file file' but did not get the warning you desrcibe.
>
>
>>>
>>> (defun poke-opt (&optional prefix)
>>>   "TODO."
>>>   (interactive "P")
>>> ...)
>>>
>>
>> This version is OK. You can call it "M-x name", "C-u M-x name", "C-u 2
>> M-x name"; wether it's safe or not depends on its body though ;-)
>>
>> Bruno
>>
Why using &optional is ok, but not ok without it?

Re: Prefix Argument and optional argument

[carlmarcos--- via Users list for the GNU Emacs text editor]

Jul 6, 2022, 11:25 by michael_heerdegen@web.de:

> carlmarcos--- via Users list for the GNU Emacs text editor
> <help-gnu-emacs@gnu.org> writes:
>
>> > You should compile your code; Emacs will say:
>> >
>> >  Warning: misplaced interactive spec: ‘(interactive P)’
>> >
>>
>> I did call `M-x byte-compile-file file' but did not get the warning
>> you desrcibe.
>>
>
> This has been added to master only recently.
>
> Michael.
>
Why is it that using &optional for prefix in good, but without &optional part is bad?
Should every time one uses the prefix argument, one has to use an optional prefix 
argument?

Re: Prefix Argument and optional argument

[Michael Heerdegen]

carlmarcos--- via Users list for the GNU Emacs text editor
<help-gnu-emacs@gnu.org> writes:

> Why is it that a warning is shown, what is the problem with it.

It warns about transposed interactive spec and docstring - a programmer
error.

> Why using &optional is ok, but not ok without it?

Non-interactive calls don't come with a prefix arg.  When you call your
function from Lisp, it's often not useful to provide something for that
argument so it makes no sense to make it mandatory.  You can make it
mandatory if the argument also has a meaning for calls from ELisp.

Michael.

Re: Prefix Argument and optional argument

[Emanuel Berg]

Michael Heerdegen wrote:

>> Why using &optional is ok, but not ok without it?
>
> Non-interactive calls don't come with a prefix arg. When you
> call your function from Lisp, it's often not useful to
> provide something for that argument so it makes no sense to
> make it mandatory. You can make it mandatory if the argument
> also has a meaning for calls from ELisp.

Mess as little as possible with all the interactive stuff
from Lisp.

Uhm, what is all the interactive stuff exactly now again?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Prefix Argument and optional argument

[Emanuel Berg]

> a programmer error

Hold on! All the stuff that has been going on for decades by
now ... don't tell me it started as a mistake?

-- 
underground experts united
https://dataswamp.org/~incal

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Emanuel Berg <incal@dataswamp.org> writes:

> > a programmer error
>
> Hold on! All the stuff that has been going on for decades by
> now ... don't tell me it started as a mistake?

My thoughts when I got those warnings for my own stuff...

Michael.

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 12:15 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> Emanuel Berg <incal@dataswamp.org> writes:
>
> > > a programmer error
> >
> > Hold on! All the stuff that has been going on for decades by
> > now ... don't tell me it started as a mistake?
>
> My thoughts when I got those warnings for my own stuff...
>
> Michael.

Is the error because one can either use the prefix argument C-u M-x poke
or use just M-x poke?  Or something else?

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> Is the error because one can either use the prefix argument C-u M-x
> poke or use just M-x poke?  Or something else?

Which error?

Michael.

Re: Prefix Argument and optional argument

[Yuri Khan]

On Thu, 7 Jul 2022 at 17:57, Michael Heerdegen <michael_heerdegen@web.de> wrote:

> > Why is it that a warning is shown, what is the problem with it.
>
> It warns about transposed interactive spec and docstring - a programmer
> error.

In the original post, the order is the same in both examples — first
the docstring, then the interactive spec, then the body forms. I do
not understand why one would cause a warning but not the other.

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 12:53 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> Christopher Dimech <dimech@gmx.com> writes:
> 
> > Is the error because one can either use the prefix argument C-u M-x
> > poke or use just M-x poke?  Or something else?
> 
> Which error?
> 
> Michael.

Have recently seen that compiling

(defun poke (prefix)
  "TODO."
  (interactive "P")
...)

gives 

Warning: misplaced interactive spec: ‘(interactive P)’

Is this associated with trying to call the function non-interactively
or because the prefix (C-u) is not always used when running the function
interactively?

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Yuri Khan <yuri.v.khan@gmail.com> writes:

> > It warns about transposed interactive spec and docstring - a programmer
> > error.
>
> In the original post, the order is the same in both examples — first
> the docstring, then the interactive spec, then the body forms. I do
> not understand why one would cause a warning but not the other.

That doesn't happen for these examples AFAICT.  These were only
skeletons, however.  I didn't follow who compiled what, I only tried to
explain the intention of the warnings.

You also get such a warning for a function with an interactive spec but
an empty body.  Maybe that had happened to someone.

Michael.

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> Have recently seen that compiling
>
> (defun poke (prefix)
>   "TODO."
>   (interactive "P")
> ...)
>
> gives 
>
> Warning: misplaced interactive spec: ‘(interactive P)’

If the order docstring + interactive spec is correct (as above), that
only happens here when the function body is empty (i.e. nothing follows
the interactive spec).  Did that happen in other cases - do you have an
example?

> Is this associated with trying to call the function non-interactively
> or because the prefix (C-u) is not always used when running the function
> interactively?

No.

Michael.

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 1:45 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> Christopher Dimech <dimech@gmx.com> writes:
> 
> > Have recently seen that compiling
> >
> > (defun poke (prefix)
> >   "TODO."
> >   (interactive "P")
> > ...)
> >
> > gives 
> >
> > Warning: misplaced interactive spec: ‘(interactive P)’
> 
> If the order docstring + interactive spec is correct (as above), that
> only happens here when the function body is empty (i.e. nothing follows
> the interactive spec).  Did that happen in other cases - do you have an
> example?

Right.  I only took the example and compiled it.
 
> > Is this associated with trying to call the function non-interactively
> > or because the prefix (C-u) is not always used when running the function
> > interactively?
> 
> No.
> 
> Michael.

It is only because body is empty then, right?

Re: Prefix Argument and optional argument

[Jean Louis]

* Christopher Dimech <dimech@gmx.com> [2022-07-07 15:56]:
> Is the error because one can either use the prefix argument C-u M-x poke
> or use just M-x poke?  Or something else?

What is this poke about?

Is it about poker?

poker is an autoloaded interactive compiled Lisp function in
‘poker.el’.

It can be invoked from the menu: Tools → Games → Texas hold 'em poker

(poker INITIAL-STACK MIN-BET PLAYERS)

Play a game of texas hold ’em poker.



-- 
Jean

Take action in Free Software Foundation campaigns:
https://www.fsf.org/campaigns

In support of Richard M. Stallman
https://stallmansupport.org/

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> It is only because body is empty then, right?

I think so, yes.

Michael.

Re: Prefix Argument and optional argument

[Stefan Monnier via Users list for the GNU Emacs text editor]

Christopher Dimech [2022-07-07 15:15:01] wrote:
> (defun poke (prefix)
>   "TODO."
>   (interactive "P")
> ...)
>
> gives 
>
> Warning: misplaced interactive spec: ‘(interactive P)’

I don't get this warning here.  Instead I get two arnings, one about the
fact that `prefix` is not used, and the other about the fact that `...`
is not a known variable.
I suspect that you compiled a slightly different code.


        Stefan

Re: Prefix Argument and optional argument

[Emanuel Berg]

Stefan Monnier via Users list for the GNU Emacs text editor wrote:

>> (defun poke (prefix)
>>   "TODO."
>>   (interactive "P")
>> ...)
>>
>> gives 
>>
>> Warning: misplaced interactive spec: ‘(interactive P)’
>
> I don't get this warning here. Instead I get two arnings,
> one about the fact that `prefix` is not used, and the other
> about the fact that `...` is not a known variable.

Do

  C-u M-x checkdoc-current-buffer RET

and learn that it also has a docstring problem:

  Argument ‘prefix’ should appear (as PREFIX) in the doc
  string

At the stage when it does nothing, it seems 'poke' has so many
problems already!

I also don't get any warnings but the ones you mention,

  Warning: Unused lexical argument `prefix'
  Warning: reference to free variable ‘...’

and that's on

  GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+
  Version 3.24.24, cairo version 1.16.0) of 2022-05-28
  [commit 707124d2b92780b4f21d72c7c62899e074fa8ced]

(Love the 'ever' command BTW,
   https://dataswamp.org/~incal/emacs-init/meta.el )

-- 
underground experts united
https://dataswamp.org/~incal

Re: Prefix Argument and optional argument

[Emanuel Berg]

Michael Heerdegen wrote:

>> It is only because body is empty then, right?
>
> I think so, yes.

With the exception of

(defun dope (_arg)
  (interactive "P") )

-- 
underground experts united
https://dataswamp.org/~incal

Re: Prefix Argument and optional argument

[Michael Heerdegen]

Emanuel Berg <incal@dataswamp.org> writes:

> With the exception of
>
> (defun dope (_arg)
>   (interactive "P") )

Indeed.  Interesting.

Michael.

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 2:08 AM
> From: "Jean Louis" <bugs@gnu.support>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Michael Heerdegen" <michael_heerdegen@web.de>, help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> * Christopher Dimech <dimech@gmx.com> [2022-07-07 15:56]:
> > Is the error because one can either use the prefix argument C-u M-x poke
> > or use just M-x poke?  Or something else?
> 
> What is this poke about?
> 
> Is it about poker?

Just a generic interactive function by the OP.
 
> poker is an autoloaded interactive compiled Lisp function in
> ‘poker.el’.
> 
> It can be invoked from the menu: Tools → Games → Texas hold 'em poker
> 
> (poker INITIAL-STACK MIN-BET PLAYERS)
> 
> Play a game of texas hold ’em poker.
> 
> 
> 
> -- 
> Jean
> 
> Take action in Free Software Foundation campaigns:
> https://www.fsf.org/campaigns
> 
> In support of Richard M. Stallman
> https://stallmansupport.org/
>

Re: Prefix Argument and optional argument

[Emanuel Berg]

Michael Heerdegen wrote:

>> With the exception of
>>
>> (defun dope (_arg)
>>   (interactive "P") )
>
> Indeed.  Interesting.

(unless (seq-every-p #'symbolp (cdr (cdr int)))
  (byte-compile-warn-x int "malformed interactive specc: %s"
    int))

lines 3116-3118 in

  /usr/local/share/emacs/29.0.50/lisp/emacs-lisp/bytecomp.el.gz

-- 
underground experts united
https://dataswamp.org/~incal

docstrings (was: Re: Prefix Argument and optional argument)

[Emanuel Berg]

Christopher Dimech wrote:

> (defun poke (prefix)
>  "TODO."
>  (interactive "P"))
>
> It is only because body is empty then, right?

The way it is implemented actually the docstring is part of
the body!

Eval this which has the same interface/signature as the
`defun' macro:

  (defmacro defun-ds (name args &rest body)
    (car body) )

And then try it:

  (defun-ds f (x) "Doc string." x)

-- 
underground experts united
https://dataswamp.org/~incal

Re: docstrings (was: Prefix Argument and optional argument)

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 5:03 AM
> From: "Emanuel Berg" <incal@dataswamp.org>
> To: help-gnu-emacs@gnu.org
> Subject: docstrings (was: Re: Prefix Argument and optional argument)
>
> Christopher Dimech wrote:
>
> > (defun poke (prefix)
> >  "TODO."
> >  (interactive "P"))
> >
> > It is only because body is empty then, right?
>
> The way it is implemented actually the docstring is part of
> the body!

Which complicates things even more.  Why are we getting warnings then!!!

> Eval this which has the same interface/signature as the
> `defun' macro:
>
>   (defmacro defun-ds (name args &rest body)
>     (car body) )
>
> And then try it:
>
>   (defun-ds f (x) "Doc string." x)
>
> --
> underground experts united
> https://dataswamp.org/~incal
>
>
>

Re: docstrings (was: Prefix Argument and optional argument)

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 5:06 AM
> From: "Christopher Dimech" <dimech@gmx.com>
> To: "Emanuel Berg" <incal@dataswamp.org>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: docstrings (was:  Prefix Argument and optional argument)
>
>
>
> > Sent: Friday, July 08, 2022 at 5:03 AM
> > From: "Emanuel Berg" <incal@dataswamp.org>
> > To: help-gnu-emacs@gnu.org
> > Subject: docstrings (was: Re: Prefix Argument and optional argument)
> >
> > Christopher Dimech wrote:
> >
> > > (defun poke (prefix)
> > >  "TODO."
> > >  (interactive "P"))
> > >
> > > It is only because body is empty then, right?
> >
> > The way it is implemented actually the docstring is part of
> > the body!
>
> Which complicates things even more.  Why are we getting warnings then!!!

Then we require a minimal test without warnings which would be

(defun poke (prefix)
  "Pokes the prefix argument
PREFIX in the prefix argument."
  (interactive "P")
  (message "poke function"))


> > Eval this which has the same interface/signature as the
> > `defun' macro:
> >
> >   (defmacro defun-ds (name args &rest body)
> >     (car body) )
> >
> > And then try it:
> >
> >   (defun-ds f (x) "Doc string." x)
> >
> > --
> > underground experts united
> > https://dataswamp.org/~incal
> >
> >
> >
>
>

Re: Prefix Argument and optional argument

[Stefan Monnier via Users list for the GNU Emacs text editor]

> (defun poke (&optional prefix)
>   "TODO"
>   (interactive "P")
>
>   (cond
>    ((equal current-prefix-arg nil)   ; no C-u
>     (setq poke-name-mode 1))
>
>    ((equal current-prefix-arg '(4))  ; C-u
>     (setq poke-name-mode 0)
>     (arktika-workbench))
>
>    ((equal current-prefix-arg 1)     ; C-u 1
>     (setq poke-name-mode 0)
>
>     (let* ( (name (read-from-minibuffer " Name: ")) )
>       (arktika-workbench name))) ) ))

The byte-compiler should tell you that the `prefix` argument is unused,
so you can remove it and replace (interactive "P") with (interactive)
and that will work just the same.

What the "P" does above is provide the (interactive) value of `prefix`
by setting it to `current-prefix-arg`.


        Stefan

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 3:12 AM
> From: "Emanuel Berg" <incal@dataswamp.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> Stefan Monnier via Users list for the GNU Emacs text editor wrote:
> 
> >> (defun poke (prefix)
> >>   "TODO."
> >>   (interactive "P")
> >> ...)
> >>
> >> gives 
> >>
> >> Warning: misplaced interactive spec: ‘(interactive P)’
> >
> > I don't get this warning here. Instead I get two arnings,
> > one about the fact that `prefix` is not used, and the other
> > about the fact that `...` is not a known variable.
> 
> Do
> 
>   C-u M-x checkdoc-current-buffer RET
> 
> and learn that it also has a docstring problem:
> 
>   Argument ‘prefix’ should appear (as PREFIX) in the doc
>   string
> 
> At the stage when it does nothing, it seems 'poke' has so many
> problems already!

Don't poke! ;)
 
> I also don't get any warnings but the ones you mention,
> 
>   Warning: Unused lexical argument `prefix'
>   Warning: reference to free variable ‘...’
> 
> and that's on
> 
>   GNU Emacs 29.0.50 (build 1, x86_64-pc-linux-gnu, GTK+
>   Version 3.24.24, cairo version 1.16.0) of 2022-05-28
>   [commit 707124d2b92780b4f21d72c7c62899e074fa8ced]
> 
> (Love the 'ever' command BTW,
>    https://dataswamp.org/~incal/emacs-init/meta.el )
> 
> -- 
> underground experts united
> https://dataswamp.org/~incal
> 
> 
>

Re: docstrings (was: Prefix Argument and optional argument)

[Emanuel Berg]

Christopher Dimech wrote:

>>> The way it is implemented actually the docstring is part
>>> of the body!
>>
>> Which complicates things even more. Why are we getting
>> warnings then!!!
>
> Then we require a minimal test without warnings which would
> be
>
> (defun poke (prefix)
>   "Pokes the prefix argument
> PREFIX in the prefix argument."
>   (interactive "P")
>   (message "poke function"))

1 warning from the byte-compiler
    Warning: Unused lexical argument `prefix'
2 warnings from (checkdoc-current-buffer t)
    First sentence should end with punctuation
    First line is not a complete sentence
130 chars

Rather ...

(defun f (x)
  "X"
  (interactive "P")
  x)

0 warnings
43 chars

-- 
underground experts united
https://dataswamp.org/~incal

Re: Prefix Argument and optional argument

[Christopher Dimech]

> Sent: Friday, July 08, 2022 at 2:58 AM
> From: "Stefan Monnier via Users list for the GNU Emacs text editor" <help-gnu-emacs@gnu.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Prefix Argument and optional argument
>
> Christopher Dimech [2022-07-07 15:15:01] wrote:
> > (defun poke (prefix)
> >   "TODO."
> >   (interactive "P")
> > ...)
> >
> > gives 
> >
> > Warning: misplaced interactive spec: ‘(interactive P)’
> 
> I don't get this warning here.  Instead I get two arnings, one about the
> fact that `prefix` is not used, and the other about the fact that `...`
> is not a known variable.
> I suspect that you compiled a slightly different code.
> 
> 
>         Stefan

Correct, I had it without the "...".
 
 
>

enforce/automate docstring correctnes (was: Re: docstrings)

[Emanuel Berg]

Instead of relying on humans not forgetting anything and also
getting the order and CAPS of the args the right way in the
docstrings, possibly after having (checkdoc-current-buffer t)
telling them about it - and incal yanking it on
gmane.emacs.help - it could be both enforced and automated
like this:

(defun (f "Advanced Functional Programming function") ((a "AFA Doku")
                                                       (o "Omega Supreme") )
  (+ a o) )

Because then, not providing docstrings everywhere would not
eval and `help-mode' would display it the correct way
including order. It'd be a Lisp OO thing; and Emacs' claim to
be "self-documenting" would ring not true but truer.

...

Why, you think the code looks too bad that way?

Compare

(defun f (a o)
"This is an Advanced Functional Programming function.

A is AFA Doku.

O is Omega Supreme."
  (+ a o) )

See? Not by much!

-- 
underground experts united
https://dataswamp.org/~incal