Supplying DOC string in a `defun' using `defvar'

Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

Can the DOC string in a `defun' be supplied using a `defvar'?

Re: Supplying DOC string in a `defun' using `defvar'

[2QdxY4RzWzUUiLuE]

On 2021-06-01 at 01:00:05 +0200,
ludvig-faddeev@gmx.com wrote:

> Can the DOC string in a `defun' be supplied using a `defvar'?

I don't know, but you can supply a value to defvar from the doc string
of a function:

    (defun some-function ()
      "hello, world"
      t)

    (defvar *some-variable*
      (documentation (symbol-function 'some-function)))

    *some-variable*

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* ludvig-faddeev@gmx.com <ludvig-faddeev@gmx.com> [2021-06-01 02:00]:
> Can the DOC string in a `defun' be supplied using a `defvar'?

Why not show your idea? I cannot understand that. I can think of this:

(defvar my-doc "Hello")

(defun my-fun ()
  my-doc
  (ignore))

It did not work, but I think it should.

my-fun is a Lisp function.

(my-fun)

Not documented.

Maybe this way:

(defmacro my-fun ()
  `(defun my-fun ()
     ,my-doc
     (ignore)))

(my-fun) ⇒ nil ;; defines function by using value defined with defvar

my-fun is a Lisp function.

(my-fun)

Hello



-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> Can the DOC string in a `defun' be supplied using a `defvar'?

In a `defun'?  No.  But you can do it this way:

(let ((toto "WHAT?!!!!"))
  (put 'bar 'function-documentation toto))

(describe-function 'bar)

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Drew Adams <drew.adams@oracle.com> writes:

> (let ((toto "WHAT?!!!!"))
>   (put 'bar 'function-documentation toto))
>
> (describe-function 'bar)

Yes, the `function-documentation` property.  Its value can even be an
expression, and that will be evaluated whenever the documentation is
requested.  In one of the simplest cases, that expression is a variable
holding the documentation:

#+begin_src emacs-lisp
(defvar my-doc "A test function

And this is its documentation")

(defun test () 1)

(put 'test 'function-documentation 'my-doc)

;; Try C-h f test RET
#+end_src

When you change the value of `my-doc' the documentation of `test'
changes magically.

There are cases in Emacs where the expression is used to generate a
docstring dynamically - `pcase' is one example.


Michael.

Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

> Sent: Tuesday, June 01, 2021 at 11:13 AM
> From: "Jean Louis" <bugs@gnu.support>
> To: ludvig-faddeev@gmx.com
> Cc: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: Supplying DOC string in a `defun' using `defvar'
>
> * ludvig-faddeev@gmx.com <ludvig-faddeev@gmx.com> [2021-06-01 02:00]:
> > Can the DOC string in a `defun' be supplied using a `defvar'?
> 
> Why not show your idea? I cannot understand that. I can think of this:
> 
> (defvar my-doc "Hello")
> 
> (defun my-fun ()
>   my-doc
>   (ignore))
> 
> It did not work, but I think it should.

I also would like for the example to work.
 
> my-fun is a Lisp function.
> 
> (my-fun)
> 
> Not documented.
> 
> Maybe this way:
> 
> (defmacro my-fun ()
>   `(defun my-fun ()
>      ,my-doc
>      (ignore)))
> 
> (my-fun) ⇒ nil ;; defines function by using value defined with defvar
> 
> my-fun is a Lisp function.
> 
> (my-fun)
> 
> Hello
> 
> 
> 
> -- 
> Jean
> 
> Take action in Free Software Foundation campaigns:
> https://www.fsf.org/campaigns
> 
> Sign an open letter in support of Richard M. Stallman
> https://stallmansupport.org/
> 
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Drew Adams <drew.adams@oracle.com> [2021-06-01 02:21]:
> > Can the DOC string in a `defun' be supplied using a `defvar'?
> 
> In a `defun'?  No.  But you can do it this way:
> 
> (let ((toto "WHAT?!!!!"))
>   (put 'bar 'function-documentation toto))
> 
> (describe-function 'bar)

If I could rename symbol then it would be possible that way to
generate functions by using `defun'



-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* ludvig-faddeev@gmx.com <ludvig-faddeev@gmx.com> [2021-06-01 02:34]:
> 
> 
> > Sent: Tuesday, June 01, 2021 at 11:13 AM
> > From: "Jean Louis" <bugs@gnu.support>
> > To: ludvig-faddeev@gmx.com
> > Cc: "Help Gnu Emacs" <help-gnu-emacs@gnu.org>
> > Subject: Re: Supplying DOC string in a `defun' using `defvar'
> >
> > * ludvig-faddeev@gmx.com <ludvig-faddeev@gmx.com> [2021-06-01 02:00]:
> > > Can the DOC string in a `defun' be supplied using a `defvar'?
> > 
> > Why not show your idea? I cannot understand that. I can think of this:
> > 
> > (defvar my-doc "Hello")
> > 
> > (defun my-fun ()
> >   my-doc
> >   (ignore))
> > 
> > It did not work, but I think it should.
> 
> I also would like for the example to work. 

The above did not work, that is why you have to think with below one,
which does work, but Drew's example is superior.

> > my-fun is a Lisp function.
> > 
> > (my-fun)
> > 
> > Not documented.
> > 
> > Maybe this way:
> > 
> > (defmacro my-fun ()
> >   `(defun my-fun ()
> >      ,my-doc
> >      (ignore)))
> > 
> > (my-fun) ⇒ nil ;; defines function by using value defined with defvar
> > 
> > my-fun is a Lisp function.
> > 
> > (my-fun)
> > 
> > Hello
> > 
> > 
> > 
> > -- 
> > Jean
> > 
> > Take action in Free Software Foundation campaigns:
> > https://www.fsf.org/campaigns
> > 
> > Sign an open letter in support of Richard M. Stallman
> > https://stallmansupport.org/
> > 
> >
> 

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

[External] : Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

A useful tool would be to allow one to append to a docstring using a variable.

User could write a brief description, and append more details from a defvar.

I like my functions to be succinct without an overly long docstring.  This makes
the implementation code readily displayed on the visible window.

> Sent: Tuesday, June 01, 2021 at 11:31 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> Drew Adams <drew.adams@oracle.com> writes:
>
> > (let ((toto "WHAT?!!!!"))
> >   (put 'bar 'function-documentation toto))
> >
> > (describe-function 'bar)
>
> Yes, the `function-documentation` property.  Its value can even be an
> expression, and that will be evaluated whenever the documentation is
> requested.  In one of the simplest cases, that expression is a variable
> holding the documentation:
>
> #+begin_src emacs-lisp
> (defvar my-doc "A test function
>
> And this is its documentation")
>
> (defun test () 1)
>
> (put 'test 'function-documentation 'my-doc)
>
> ;; Try C-h f test RET
> #+end_src
>
> When you change the value of `my-doc' the documentation of `test'
> changes magically.
>
> There are cases in Emacs where the expression is used to generate a
> docstring dynamically - `pcase' is one example.
>
>
> Michael.
>
>
>

Re: Supplying DOC string in a `defun' using `defvar'

[2QdxY4RzWzUUiLuE]

On 2021-06-01 at 02:13:00 +0300,
Jean Louis <bugs@gnu.support> wrote:

> * ludvig-faddeev@gmx.com <ludvig-faddeev@gmx.com> [2021-06-01 02:00]:
> > Can the DOC string in a `defun' be supplied using a `defvar'?
> 
> Why not show your idea? I cannot understand that. I can think of this:
> 
> (defvar my-doc "Hello")
> 
> (defun my-fun ()
>   my-doc
>   (ignore))
> 
> It did not work, but I think it should.

Consider the following:

    (defvar *string* "hello, world")
    (defun foo ()
      *string*)

What would foo return?  What would its doc string be?

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* 2QdxY4RzWzUUiLuE@potatochowder.com <2QdxY4RzWzUUiLuE@potatochowder.com> [2021-06-01 03:15]:
> > It did not work, but I think it should.
> 
> Consider the following:
> 
>     (defvar *string* "hello, world")
>     (defun foo ()
>       *string*)
> 
> What would foo return?  What would its doc string be?

That one did not work, it was demonstration that it does not work. 

And here again the solution which does work:

(defvar my-doc "Hello there")

(defmacro my-fun ()
  `(defun my-fun ()
     ,my-doc
     (ignore)))

To define function run: (my-fun) ⇒ my-fun

(documentation 'my-fun) ⇒ "Hello there"

Funny, as to define the function one defines macro that
overwrites itself by the function calling the macro first time.


-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

ludvig-faddeev@gmx.com writes:

> A useful tool would be to allow one to append to a docstring using a
> variable.

It's already easy to that using the property, no?  Why would we need
another tool?  Unless I don't understand your suggestion...?

Michael.

[External] : Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

I would be interested to study an example on how to append to the docstring.

> Sent: Tuesday, June 01, 2021 at 12:29 PM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: ludvig-faddeev@gmx.com
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> ludvig-faddeev@gmx.com writes:
>
> > A useful tool would be to allow one to append to a docstring using a
> > variable.
>
> It's already easy to that using the property, no?  Why would we need
> another tool?  Unless I don't understand your suggestion...?
>
> Michael.
>
>

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Jean Louis <bugs@gnu.support> [2021-06-01 03:28]:
> * 2QdxY4RzWzUUiLuE@potatochowder.com <2QdxY4RzWzUUiLuE@potatochowder.com> [2021-06-01 03:15]:
> > > It did not work, but I think it should.
> > 
> > Consider the following:
> > 
> >     (defvar *string* "hello, world")
> >     (defun foo ()
> >       *string*)
> > 
> > What would foo return?  What would its doc string be?
> 
> That one did not work, it was demonstration that it does not work. 
> 
> And here again the solution which does work:
> 
> (defvar my-doc "Hello there")
> 
> (defmacro my-fun ()
>   `(defun my-fun ()
>      ,my-doc
>      (ignore)))
> 
> To define function run: (my-fun) ⇒ my-fun
> 
> (documentation 'my-fun) ⇒ "Hello there"
> 
> Funny, as to define the function one defines macro that
> overwrites itself by the function calling the macro first time.

Now I wonder could it be all written this way:

;; -*- lexical-binding: t; -*-

(defvar my-doc "Hello there again2")

(let ()
  (defmacro my-fun ()
    `(defun my-fun ()
       ,my-doc
       (ignore)))
  (my-fun))

;; (documentation 'my-fun) ⇒ "Hello there again2"

So it works that way even with lexical-binding: t 

But that is, while funny, not practical and not elegant, Drew's
solution is there, did you read it?


-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Jean Louis <bugs@gnu.support> writes:

> (defvar my-doc "Hello there")
>
> (defmacro my-fun ()
>   `(defun my-fun ()
>      ,my-doc
>      (ignore)))

Would you want the body to be stored in another defvar?  Then your code
would be even smaller.

I'm only partially joking, actually, not at all - is the function's
documentation for your code's readers really that much less important
than its code?  Maybe it's even the other way round?

Michael.

Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

> Sent: Tuesday, June 01, 2021 at 12:40 PM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Supplying DOC string in a `defun' using `defvar'
>
> Jean Louis <bugs@gnu.support> writes:
>
> > (defvar my-doc "Hello there")
> >
> > (defmacro my-fun ()
> >   `(defun my-fun ()
> >      ,my-doc
> >      (ignore)))
>
> Would you want the body to be stored in another defvar?  Then your code
> would be even smaller.
>
> I'm only partially joking, actually, not at all - is the function's
> documentation for your code's readers really that much less important
> than its code?  Maybe it's even the other way round?

I would still want to provide it, but want to keep user centered and developer
centered parts to be distinct.  Have worked with the literate programming environment
introduced by Knuth in the early 1980s but have not bought the result.

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Michael Heerdegen <michael_heerdegen@web.de> [2021-06-01 03:40]:
> Jean Louis <bugs@gnu.support> writes:
> 
> > (defvar my-doc "Hello there")
> >
> > (defmacro my-fun ()
> >   `(defun my-fun ()
> >      ,my-doc
> >      (ignore)))
> 
> Would you want the body to be stored in another defvar?  Then your code
> would be even smaller.
> 
> I'm only partially joking, actually, not at all - is the function's
> documentation for your code's readers really that much less important
> than its code?  Maybe it's even the other way round?

Yes, obviously it is not practical, but it works. And is not me who
defines those functions. I am generating 50+ function aliases by
Drew's suggestion:

(defun hyperscope-generate-add-functions-by-hyperdocument-types ()
  (let ((types (hyperscope-hyperdocument-types)))
    (while types
      (let* ((type (pop types))
	     (id (nth 0 type))
	     (type (nth 1 type))
	     (type-name type)
	     (type (downcase (string-replace " " "-" type)))
	     (new-function-name (format "hyperscope-add-new-%s-hyperdocument" type)))
	(defalias (intern new-function-name)
	  (lambda ()
	    (interactive)
	    (let* ((parent (hyperscope-select-set))
		   (prompt (format "New `%s' hyperdocument name: " type-name))
		   (name (read-from-minibuffer prompt)))
	      (hlink-add-generic name "" id parent nil)))
	  (format "Add new `%s' hyperdocument to Hyperscope." type-name))))))

(hyperscope-generate-add-functions-by-hyperdocument-types)

This technique is handy as then user can simply add new type in the
database, visually, interactively, and new function is generated as a
hook that helps to add the new type. Even new key binding could be
generated automatically.

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

ludvig-faddeev@gmx.com writes:

> I would be interested to study an example on how to append to the
> docstring.

This makes only sense if the resulting docstring is dynamically created.
Else you could just provide the complete string at once.

If you want to study such an example then the documentation of `pcase'
in the Emacs sources is a good one.

Michael.

Re: Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Jean Louis <bugs@gnu.support> writes:

> > > (defmacro my-fun ()
> > >   `(defun my-fun ()
> > >      ,my-doc
> > >      (ignore)))

> > I'm only partially joking, actually, not at all - is the function's
> > documentation for your code's readers really that much less important
> > than its code?  Maybe it's even the other way round?
>
> Yes, obviously it is not practical, but it works. And is not me who
> defines those functions. I am generating 50+ function aliases by
> Drew's suggestion: [...]

Such a loop with even automatically generated docstrings using a
template is of course a different issue that doing that for one function
as in the example above.

Michael.

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Michael Heerdegen <michael_heerdegen@web.de> [2021-06-01 04:28]:
> Jean Louis <bugs@gnu.support> writes:
> 
> > > > (defmacro my-fun ()
> > > >   `(defun my-fun ()
> > > >      ,my-doc
> > > >      (ignore)))
> 
> > > I'm only partially joking, actually, not at all - is the function's
> > > documentation for your code's readers really that much less important
> > > than its code?  Maybe it's even the other way round?
> >
> > Yes, obviously it is not practical, but it works. And is not me who
> > defines those functions. I am generating 50+ function aliases by
> > Drew's suggestion: [...]
> 
> Such a loop with even automatically generated docstrings using a
> template is of course a different issue that doing that for one function
> as in the example above.

Problem is however following:

L in dired loads the file and all other functions get loaded but those
not.

If I however, manually evaluate it then I get functions.

Do you know why that could be?

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

[External] : Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

Is it possible to define a function that sets a documentation string and
then calls

(put 'wyfunc
     'function-documentation 'mydetail)




> Sent: Tuesday, June 01, 2021 at 1:08 PM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> ludvig-faddeev@gmx.com writes:
>
> > I would be interested to study an example on how to append to the
> > docstring.
>
> This makes only sense if the resulting docstring is dynamically created.
> Else you could just provide the complete string at once.
>
> If you want to study such an example then the documentation of `pcase'
> in the Emacs sources is a good one.
>
> Michael.
>
>
>

Re: Supplying DOC string in a `defun' using `defvar'

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

> (defvar my-doc "Hello")
>
> (defun my-fun ()
>   my-doc
>   (ignore))
>
> It did not work, but I think it should.

Try:

    (defvar my-doc "foobar")
    (defun (x)
      (:documentation my-doc)
      (+ x 42))


-- Stefan

Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Tuesday, June 01, 2021 at 3:26 PM
> 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: Supplying DOC string in a `defun' using `defvar'
>
> > (defvar my-doc "Hello")
> >
> > (defun my-fun ()
> >   my-doc
> >   (ignore))
> >
> > It did not work, but I think it should.
>
> Try:
>
>     (defvar my-doc "foobar")
>     (defun (x)
>       (:documentation my-doc)
>       (+ x 42))

Have tried this but emacs is still saying "Not documented."

Re: Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Jean Louis <bugs@gnu.support> writes:

> L in dired loads the file and all other functions get loaded but those
> not.
>
> If I however, manually evaluate it then I get functions.

Did you already try a debugger?

Regards,

Michael.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

ludvig-faddeev@gmx.com writes:

> Is it possible to define a function that sets a documentation string and
> then calls
>
> (put 'wyfunc
>      'function-documentation 'mydetail)

You don't need a variable as an intermediate step in that case at all,
that would be redundant -- because can use `get' to look up what is
stored in the function-documentation property of your symbol so far.

Use `put' to set it to something else, whether that reuses the old value
or not.  There is really no magic here at all, it's just that trivial.
That symbol property is where the documentation is stored, just like a
variable - only the way of getting and setting the value looks different
compared to a variable.

If you need a more concrete suggestion, I need to know more about your
use case.


Regards,

Michael.

Re: Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> > Try:
> >
> >     (defvar my-doc "foobar")
> >     (defun (x)
> >       (:documentation my-doc)
> >       (+ x 42))
>
> Have tried this but emacs is still saying "Not documented."

Stefan typed too quickly, he forgot the function name in the defun - so
it probably should be

(defun my-fun (x)
  (:documentation my-doc)
  (+ x 42))

Michael.

Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 2:31 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Supplying DOC string in a `defun' using `defvar'
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> > > Try:
> > >
> > >     (defvar my-doc "foobar")
> > >     (defun (x)
> > >       (:documentation my-doc)
> > >       (+ x 42))
> >
> > Have tried this but emacs is still saying "Not documented."
>
> Stefan typed too quickly, he forgot the function name in the defun - so
> it probably should be
>
> (defun my-fun (x)
>   (:documentation my-doc)
>   (+ x 42))
>
> Michael.

Had noticed what happened, but (:documentation my-doc) is not taking effect and
get "function not documented".


>

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> > (defun my-fun (x)
> >   (:documentation my-doc)
> >   (+ x 42))
> 
> Had noticed what happened, but (:documentation my-doc) is not taking effect
> and get "function not documented".

It works for me.  However, at least in Emacs 27.2,
`:documentation' is not documented in the Elisp manual,
except for use by `cl-generic'.  That seems like a bug.

(But `:doc' is documented, for use by `defcustom'.
And grepping shows that there is also `:doc-spec'.)

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 3:01 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Christopher Dimech" <dimech@gmx.com>, "Michael Heerdegen" <michael_heerdegen@web.de>
> Cc: "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: RE: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > > (defun my-fun (x)
> > >   (:documentation my-doc)
> > >   (+ x 42))
> > 
> > Had noticed what happened, but (:documentation my-doc) is not taking effect
> > and get "function not documented".
> 
> It works for me.  However, at least in Emacs 27.2,
> `:documentation' is not documented in the Elisp manual,
> except for use by `cl-generic'.  That seems like a bug.

I have used emacs-27.1 and emacs-28.0.50.  Doing "C-h f my-fun"
gives

--------

my-fun is an interactive Lisp function in ‘gungadin.el’.

(my-fun X)

Not documented.

---------
 
> (But `:doc' is documented, for use by `defcustom'.
> And grepping shows that there is also `:doc-spec'.)
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

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

> my-fun is an interactive Lisp function in ‘gungadin.el’.
>
> (my-fun X)
>
> Not documented.

You most likely used the old dynamically scoped ELisp dialect.
In Emacs-28 you should see in the modeline "ELisp/d" where the "/d" is
highlighted in orange to bring your attention to your use of that old
dialect and encourage you to change it (e.g. by clicking on it).


        Stefan

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> It works for me.  However, at least in Emacs 27.2,
> `:documentation' is not documented in the Elisp manual,
> except for use by `cl-generic'.  That seems like a bug.
                     ^^^^^^^^^^

That should have been `cl-defgeneric'.  Seems like
this should be documented for `defun' as well as
`cl-defgeneric'.

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Michael Heerdegen <michael_heerdegen@web.de> [2021-06-01 16:40]:
> Jean Louis <bugs@gnu.support> writes:
> 
> > L in dired loads the file and all other functions get loaded but those
> > not.
> >
> > If I however, manually evaluate it then I get functions.
> 
> Did you already try a debugger?

How could I invoke debugger on loading the file?

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Michael Heerdegen <michael_heerdegen@web.de> [2021-06-01 17:32]:
> Christopher Dimech <dimech@gmx.com> writes:
> 
> > > Try:
> > >
> > >     (defvar my-doc "foobar")
> > >     (defun (x)
> > >       (:documentation my-doc)
> > >       (+ x 42))
> >
> > Have tried this but emacs is still saying "Not documented."
> 
> Stefan typed too quickly, he forgot the function name in the defun - so
> it probably should be
> 

(defun my-fun (x)
  (:documentation my-doc)
  (+ x 42))

That does not work.


-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 3:38 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: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > my-fun is an interactive Lisp function in ‘gungadin.el’.
> >
> > (my-fun X)
> >
> > Not documented.
> 
> You most likely used the old dynamically scoped ELisp dialect.
> In Emacs-28 you should see in the modeline "ELisp/d" where the "/d" is
> highlighted in orange to bring your attention to your use of that old
> dialect and encourage you to change it (e.g. by clicking on it).
> 
> Stefan
 
And change it to what???  That is the whole point.  I installed Emacs 28  
and need to know how to do things for Emacs 28.  If you want the new dialect
why not use lexical binding by default?

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Eli Zaretskii]

> From: Christopher Dimech <dimech@gmx.com>
> Date: Tue, 1 Jun 2021 20:20:35 +0200
> Cc: help-gnu-emacs@gnu.org
> 
> If you want the new dialect why not use lexical binding by default?

Because we are not yet ready for that.  It will happen later.

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 6:25 AM
> From: "Eli Zaretskii" <eliz@gnu.org>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > From: Christopher Dimech <dimech@gmx.com>
> > Date: Tue, 1 Jun 2021 20:20:35 +0200
> > Cc: help-gnu-emacs@gnu.org
> >
> > If you want the new dialect why not use lexical binding by default?
>
> Because we are not yet ready for that.  It will happen later.

Oh bugger !  At the moment, is it complicated to tell users what to change
and do things.  What would you suggest for this documentation appending
thing?

Re: Supplying DOC string in a `defun' using `defvar'

[Nick Dokos]

Christopher Dimech <dimech@gmx.com> writes:

>> Sent: Tuesday, June 01, 2021 at 3:26 PM

>> 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: Supplying DOC string in a `defun' using `defvar'
>>
>> > (defvar my-doc "Hello")
>> >
>> > (defun my-fun ()
>> >   my-doc
>> >   (ignore))
>> >
>> > It did not work, but I think it should.
>>
>> Try:
>>
>>     (defvar my-doc "foobar")
>>     (defun (x)
>>       (:documentation my-doc)
>>       (+ x 42))
>
> Have tried this but emacs is still saying "Not documented."
>

It should be

  (defun my-fun (x)
     ...

Then try `C-h f my-fun'.
-- 
Nick

"There are only two hard problems in computer science: cache
invalidation, naming things, and off-by-one errors." -Martin Fowler

Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 6:51 AM
> From: "Nick Dokos" <ndokos@gmail.com>
> To: help-gnu-emacs@gnu.org
> Subject: Re: Supplying DOC string in a `defun' using `defvar'
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> >> Sent: Tuesday, June 01, 2021 at 3:26 PM
>
> >> 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: Supplying DOC string in a `defun' using `defvar'
> >>
> >> > (defvar my-doc "Hello")
> >> >
> >> > (defun my-fun ()
> >> >   my-doc
> >> >   (ignore))
> >> >
> >> > It did not work, but I think it should.
> >>
> >> Try:
> >>
> >>     (defvar my-doc "foobar")
> >>     (defun (x)
> >>       (:documentation my-doc)
> >>       (+ x 42))
> >
> > Have tried this but emacs is still saying "Not documented."
> >
>
> It should be
>
>   (defun my-fun (x)
>      ...
>
> Then try `C-h f my-fun'.
> --
> Nick

Had realised that, but the current discussion has shifted to lexical binding.
But this has still not solved the problem, and I am still getting

"my-fun not documented"

[External] : Supplying DOC string in a `defun' using `defvar'

[ludvig-faddeev]

> Sent: Wednesday, June 02, 2021 at 2:26 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> ludvig-faddeev@gmx.com writes:
>
> > Is it possible to define a function that sets a documentation string and
> > then calls
> >
> > (put 'wyfunc
> >      'function-documentation 'mydetail)
>
> You don't need a variable as an intermediate step in that case at all,
> that would be redundant -- because can use `get' to look up what is
> stored in the function-documentation property of your symbol so far.

Could I ust use the string directly in the "put" statement?

(put 'myfunc
     'function-documentation <doc-string>)

I want to only have a brief docstring in the function definition, with more details
done somewhere else (which at the current time I can do using a put).

I could call the following function

(defun defun-detail (fname detail)
   "Put DETAIL in function-documentation property of FNAME.
Usage:  (defun-detail 'fname 'detail)"

   (put fname 'function-documentation detail))

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

(defvar detail-ziggurat-bufr-wlabel
   "Generate new temporary buffer with a user defined label.
User gets asked for a label name through thu mini-buffer.

Usage:  C-u M-x ziggurat-bufr-wlabel
        M-x ziggurat-bufr-wlabel

One can use a key-sequence to call ziggurat-bufr-wlabel

  (global-unset-key (kbd \"<f5>\"))
  (global-set-key (kbd \"<f5>\")  #'ziggurat-bufr-wlabel)"
  "Detailed doc-string for ziggurat-bufr-wlabel")

--------

;; puts documentation in function-documentation property
(defun-detail 'ziggurat-bufr-wlabel 'detail-ziggurat-bufr-wlabel)

-------

(defun ziggurat-bufr-wlabel ()
  "Generate new temporary buffer with a user defined label."

  (interactive)
  (ziggurat-bufr
     (read-from-minibuffer "Buffer name: ")))

--------

> Use `put' to set it to something else, whether that reuses the old value
> or not.  There is really no magic here at all, it's just that trivial.
> That symbol property is where the documentation is stored, just like a
> variable - only the way of getting and setting the value looks different
> compared to a variable.
>
> If you need a more concrete suggestion, I need to know more about your
> use case.
>
>
> Regards,
>
> Michael.
>
>
>
>

Re: Supplying DOC string in a `defun' using `defvar'

[Robert Thorpe]

I tried this example out.  In a emacs-lisp-mode buffer I put the following:

(setq lexical-binding t)

(defvar my-doc "foobar")

(defun my-fun (x)
  (:documentation my-doc)
  (+ x 42))

I evaluated each of them in turn.  After that when I do C-h f on my-fun
I get "foobar".  What is a little strange is that Emacs tells me that
my-fun is a "Lisp closure".

If I *don't* have the first line (the lexical-binding one) then this
doesn't work.  In that case C-h f tells me that my-fun is a "Lisp
function" and has no documentation.

BR,
Robert Thorpe

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

ludvig-faddeev@gmx.com writes:

> Could I ust use the string directly in the "put" statement?
>
> (put 'myfunc
>      'function-documentation <doc-string>)

Sure.


> (defun defun-detail (fname detail)
>    "Put DETAIL in function-documentation property of FNAME.
> Usage:  (defun-detail 'fname 'detail)"
>
>    (put fname 'function-documentation detail))

> [...]

At the first look that all looks ok to me.


Regards,

Michael

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> > > > (defun my-fun (x)
> > > >   (:documentation my-doc)
> > > >   (+ x 42))

> I have used emacs-27.1 and emacs-28.0.50.  Doing "C-h f my-fun"
> gives
>
> --------
>
> my-fun is an interactive Lisp function in ‘gungadin.el’.
>
> (my-fun X)
>
> Not documented.

Seems that syntax is only meaningful in lexically binding Elisp.

Michael.

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 10:39 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Drew Adams" <drew.adams@oracle.com>, "help-gnu-emacs" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> Christopher Dimech <dimech@gmx.com> writes:
> 
> > > > > (defun my-fun (x)
> > > > >   (:documentation my-doc)
> > > > >   (+ x 42))
> 
> > I have used emacs-27.1 and emacs-28.0.50.  Doing "C-h f my-fun"
> > gives
> >
> > --------
> >
> > my-fun is an interactive Lisp function in ‘gungadin.el’.
> >
> > (my-fun X)
> >
> > Not documented.
> 
> Seems that syntax is only meaningful in lexically binding Elisp.

Is there no syntax that works for dynamic and lexical binding?
 
> Michael.
>

Re: Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Jean Louis <bugs@gnu.support> writes:

> How could I invoke debugger on loading the file?

Not directly on loading.  Debug the
`hyperscope-generate-add-functions-by-hyperdocument-types' call (that is
performed when loading the file).

Depending on whether you want to use Edebug or the "standard" debugger,
instrument that function before loading the file, or use
`debug-on-entry'.  More details in the manual.

Michael.

Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 10:15 AM
> From: "Robert Thorpe" <rt@robertthorpeconsulting.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: ndokos@gmail.com, help-gnu-emacs@gnu.org
> Subject: Re: Supplying DOC string in a `defun' using `defvar'
>
> I tried this example out.  In a emacs-lisp-mode buffer I put the following:
>
> (setq lexical-binding t)
>
> (defvar my-doc "foobar")
>
> (defun my-fun (x)
>   (:documentation my-doc)
>   (+ x 42))
>
> I evaluated each of them in turn.  After that when I do C-h f on my-fun
> I get "foobar".  What is a little strange is that Emacs tells me that
> my-fun is a "Lisp closure".
>
> If I *don't* have the first line (the lexical-binding one) then this
> doesn't work.  In that case C-h f tells me that my-fun is a "Lisp
> function" and has no documentation.

Correct

> BR,
> Robert Thorpe
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

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

>> dialect and encourage you to change it (e.g. by clicking on it).
> And change it to what???  That is the whole point.

That's right; clicking on it *is* the whole point.


        Stefan

Re: [External] : Supplying DOC string in a `defun' using `defvar'

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

>> Seems that syntax is only meaningful in lexically binding Elisp.
> Is there no syntax that works for dynamic and lexical binding?

Why would you need it to work in the old dynbound dialect?
Nowadays I see no good reason to use the old dialect for new code.


        Stefan

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Wednesday, June 02, 2021 at 2:55 PM
> 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: [External] : Supplying DOC string in a `defun' using `defvar'
>
> >> Seems that syntax is only meaningful in lexically binding Elisp.
> > Is there no syntax that works for dynamic and lexical binding?
>
> Why would you need it to work in the old dynbound dialect?
> Nowadays I see no good reason to use the old dialect for new code.

Then, ultimately, there will not be any dynamic binding?  From my point of view,
the docstring should have nothing to do with either dynamic or lexical binding.

The latest discussion has centered around using

(put 'myfunc 'function-documentation <doc-string>)

And that lexical binding would become default, but not yet.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Christopher Dimech <dimech@gmx.com> [2021-06-02 07:56]:
> Then, ultimately, there will not be any dynamic binding?

Just to say, I hope not. On the other hand I don't think it would be
good, or friendly to simply enforce it over all of the Emacs Lisp, and
thus people as programmers.

> From my point of view, the docstring should have nothing to do with
> either dynamic or lexical binding.

Definitely, it is one of weirdest encounters, totally out of habits
within Lisp.

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> Then, ultimately, there will not be any dynamic binding?

Not at all: the old dialect is called "dynamically bound" because its
most recognizable property is that it offers only dynamic binding,
whereas the new dialect has both.

> From my point of view, the docstring should have nothing to do with
> either dynamic or lexical binding.

No, but it's a new language feature, so it makes sense that you need to
use the new dialect for it be available.

> And that lexical binding would become default, but not yet.

The "default" is largely irrelevant: you get to choose for every ELisp
file which dialect it uses.

Have you tried to click on that "/d"?


        Stefan

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 1:09 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > Then, ultimately, there will not be any dynamic binding?
>
> Not at all: the old dialect is called "dynamically bound" because its
> most recognizable property is that it offers only dynamic binding,
> whereas the new dialect has both.

> > From my point of view, the docstring should have nothing to do with
> > either dynamic or lexical binding.
>
> No, but it's a new language feature, so it makes sense that you need to
> use the new dialect for it be available.

I understand

> > And that lexical binding would become default, but not yet.
>
> The "default" is largely irrelevant: you get to choose for every ELisp
> file which dialect it uses.

Would that not be excessive.  Should new users worry about dynamic and
lexical binding when playing the elisp?  I would say that the designation
should be normally set by the user, except when he has a reason for doing
things differently.

> Have you tried to click on that "/d"?

It introduced  -*- lexical-binding: t; -*- at the top of the file

Is that enough or would I need additional setup commands?

>         Stefan
>
>

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 1:35 AM
> From: "Christopher Dimech" <dimech@gmx.com>
> To: "Stefan Monnier" <monnier@iro.umontreal.ca>
> Cc: help-gnu-emacs@gnu.org
> Subject: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > Sent: Thursday, June 03, 2021 at 1:09 AM
> > From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> > To: "Christopher Dimech" <dimech@gmx.com>
> > Cc: help-gnu-emacs@gnu.org
> > Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
> >
> > > Then, ultimately, there will not be any dynamic binding?
> >
> > Not at all: the old dialect is called "dynamically bound" because its
> > most recognizable property is that it offers only dynamic binding,
> > whereas the new dialect has both.
>
> > > From my point of view, the docstring should have nothing to do with
> > > either dynamic or lexical binding.
> >
> > No, but it's a new language feature, so it makes sense that you need to
> > use the new dialect for it be available.
>
> I understand
>
> > > And that lexical binding would become default, but not yet.
> >
> > The "default" is largely irrelevant: you get to choose for every ELisp
> > file which dialect it uses.
>
> Would that not be excessive.  Should new users worry about dynamic and
> lexical binding when playing the elisp?  I would say that the designation
> should be normally set by the user, except when he has a reason for doing
> things differently.

Small mistake there, meant to say that the designation should *not* be
frequently set by the user.  Bet eventually things will stick to lexical
from what I have captured.  I like lexical binding but can see the usefulness
of dynamic binding to be available at user request.

> > Have you tried to click on that "/d"?
>
> It introduced  -*- lexical-binding: t; -*- at the top of the file
>
> Is that enough or would I need additional setup commands?
>
> >         Stefan
> >
> >
>
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

>> Have you tried to click on that "/d"?
>
> It introduced  -*- lexical-binding: t; -*- at the top of the file

Indeed.

> Is that enough or would I need additional setup commands?

Does (:documentation <foo>) work now?


        Stefan

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> > From my point of view, the docstring should have 
> > nothing to do with either dynamic or lexical binding.
> 
> No, but

I guess (hope) that your "No, but" really means "Yes,
but", and that you agree that it _should_ indeed have
nothing to do with dynamic or lexical binding.

> it's a new language feature, so it makes sense that 
> you need to use the new dialect for it be available.

I don't see how that makes sense at all.  It doesn't
follow logically that every "new language feature"
must work _only_ with the lexical binding dialect
turned ON.

As you say, the "lexical" dialect supports both
lexical and dynamic binding.

And other things being equal, a new feature should,
likewise, support both lexical and dynamic binding.

But it doesn't follow that a new feature shouldn't
work with the "dynamic" dialect, when no lexical
bindings are involved.

Regardless of the "dialect" used (i.e., whether
var `lexical-binding' is nil or non-nil), there's
nothing in the example used in this thread that
makes use of any lexical bindings (beyond the
binding of local variable `x'):

 (defvar my-doc "Whatever...")	
 (defun my-fun (x)
   (:documentation my-doc)
   (+ x 42))

That lexical binding is available in Emacs Lisp now
is a good thing.  That both it and dynamic binding
should be available from now on is a good thing.
And turning on such support for both by default will
also be a good thing, when that happens.

But that users should be required to explicitly turn
it on now in a buffer where you evaluate such an
example (which shouldn't need and doesn't make use
of lexical bindings) makes no sense at all, to me.
But please let me know what I'm missing about this.

At least such a requirement doesn't follow from
the fact that `:documentation' is "a new language
feature" ... unless you can show that this new
feature somehow requires lexical binding support
even for such an example.

The question, I think, is why shouldn't using
`:documentation' work regardless of whether lexical
binding is turned on for the current buffer?

> You get to choose for every ELisp file which
> dialect it uses.

Emacs turning on the "lexical" dialect (a misnomer)
by default, so that both lexical and binding are
supported out of the box, will be welcome.

Until then, "get to choose" should really mean
_get_ to choose.  It shouldn't mean that in order
to use such a "new feature" you _must_ explicitly
turn on the "lexical" dialect, even when no lexical
binding is involved.

For now, the default is the "dynamic" dialect (also
a misnomer, as you pointed out).  For now, new
features that don't inherently require the use of
lexical binding should _just work_ for both
"dialects".

Unless I'm missing something...  Does this new
feature (`:documentation') inherently require the
"lexical" dialect?  Is such an example, which
makes no use of lexical bindings, inherently
incompatible with the "dynamic" dialect?

FW: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

[Forwarding to the list, which got dropped from
`Reply All' for some reason.]
___

Sent: Tuesday, June 1, 2021 9:36 AM To: 'Stefan Monnier'

> You most likely used the old dynamically scoped ELisp dialect.
> In Emacs-28 you should see in the modeline "ELisp/d" where the "/d" is
> highlighted in orange to bring your attention to your use of that old
> dialect and encourage you to change it (e.g. by clicking on it).

Why is `:documentation' supported only for lexical-binding buffers?

Reason in terms of user expectation behavior?
Reason in terms of implementation ease/feasiblity?

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 3:08 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> >> Have you tried to click on that "/d"?
> >
> > It introduced  -*- lexical-binding: t; -*- at the top of the file
>
> Indeed.
>
> > Is that enough or would I need additional setup commands?
>
> Does (:documentation <foo>) work now?
>
>
>         Stefan

It does work.  So now I can pass a variable as documuntation.

The next thing is to first write a brief description as a normal string
- as normally done with defun, then append the detail string after that.

(defvar detail "this is a detailed description")

(defun myfun (x)
  (:documentation (concat "Brief\n" detail))
  (+ x 42))

This is working.  Would you be satisfied with the approach?

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 3:59 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Help-Gnu-Emacs (help-gnu-emacs@gnu.org)" <help-gnu-emacs@gnu.org>
> Cc: "Stefan Monnier" <monnier@iro.umontreal.ca>
> Subject: FW: [External] : Supplying DOC string in a `defun' using `defvar'
>
> [Forwarding to the list, which got dropped from
> `Reply All' for some reason.]
> ___
>
> Sent: Tuesday, June 1, 2021 9:36 AM To: 'Stefan Monnier'
>
> > You most likely used the old dynamically scoped ELisp dialect.
> > In Emacs-28 you should see in the modeline "ELisp/d" where the "/d" is
> > highlighted in orange to bring your attention to your use of that old
> > dialect and encourage you to change it (e.g. by clicking on it).
>
> Why is `:documentation' supported only for lexical-binding buffers?

Reason in terms of user expectation behavior?  Yes

Reason in terms of implementation ease/feasiblity?
If the implementation is difficult or unfeasible, the design might be at fault.

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> > Why is `:documentation' supported only for
> > lexical-binding buffers?
>
> Reason in terms of user expectation behavior?  Yes

Why on earth would a user expect that :documentation
works only if `lexical-binding' is non-nil, even for
code that involves no lexically bound variables?

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 5:24 AM
> From: "Drew Adams" <drew.adams@oracle.com>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Help-Gnu-Emacs (help-gnu-emacs@gnu.org)" <help-gnu-emacs@gnu.org>, "Stefan Monnier" <monnier@iro.umontreal.ca>
> Subject: RE: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > > Why is `:documentation' supported only for
> > > lexical-binding buffers?
> >
> > Reason in terms of user expectation behavior?  Yes
>
> Why on earth would a user expect that :documentation
> works only if `lexical-binding' is non-nil, even for
> code that involves no lexically bound variables?

Quite Right.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

Drew Adams [2021-06-02 15:53:31] wrote:
>> > From my point of view, the docstring should have 
>> > nothing to do with either dynamic or lexical binding.
>> No, but
> I guess (hope) that your "No, but" really means "Yes,
> but", and that you agree that it _should_ indeed have
> nothing to do with dynamic or lexical binding.
>> it's a new language feature, so it makes sense that 
>> you need to use the new dialect for it be available.
> I don't see how that makes sense at all.  It doesn't
> follow logically that every "new language feature"
> must work _only_ with the lexical binding dialect
> turned ON.

Indeed it doesn't mean it would be bad to support
(:documentation <foo>) in the dynbound case.  But it's argument for not
bothering to do so.


        Stefan

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Stefan Monnier <monnier@iro.umontreal.ca> [2021-06-02 21:37]:
> Drew Adams [2021-06-02 15:53:31] wrote:
> >> > From my point of view, the docstring should have 
> >> > nothing to do with either dynamic or lexical binding.
> >> No, but
> > I guess (hope) that your "No, but" really means "Yes,
> > but", and that you agree that it _should_ indeed have
> > nothing to do with dynamic or lexical binding.
> >> it's a new language feature, so it makes sense that 
> >> you need to use the new dialect for it be available.
> > I don't see how that makes sense at all.  It doesn't
> > follow logically that every "new language feature"
> > must work _only_ with the lexical binding dialect
> > turned ON.
> 
> Indeed it doesn't mean it would be bad to support
> (:documentation <foo>) in the dynbound case.  But it's argument for not
> bothering to do so.

That feature is kind of hidden, as the only place where it is
mentioned in the manual is at (elisp) Generic Functions

 -- Macro: cl-defgeneric name arguments [documentation]
          [options-and-methods...] &rest body
     This macro defines a generic function with the specified NAME and
     ARGUMENTS.  If BODY is present, it provides the default
     implementation.  If DOCUMENTATION is present (it should always be),
     it specifies the documentation string for the generic function, in
     the form ‘(:documentation DOCSTRING)’.  The optional
     OPTIONS-AND-METHODS can be one of the following forms:

So it is not official feature, as `defun' and `cl-defgeneric' are not
same and there is nothing about it explained in `defun' doc-string



-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> That feature is kind of hidden, as the only place where it is
> mentioned in the manual is at (elisp) Generic Functions
>
>      If DOCUMENTATION is present (it should always be),
>      it specifies the documentation string for the generic 
>      function, in the form ‘(:documentation DOCSTRING)’.

https://lists.gnu.org/archive/html/help-gnu-emacs/2021-06/msg00027.html

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> >> it's a new language feature, so it makes sense that
> >> you need to use the new dialect for it be available.
> >
> > I don't see how that makes sense at all.  It doesn't
> > follow logically that every "new language feature"
> > must work _only_ with the lexical binding dialect
> > turned ON.
>
> Indeed it doesn't mean it would be bad to support
> (:documentation <foo>) in the dynbound case.  But
> it's argument for not bothering to do so.

As the examples in this thread indicate, users will
be mightily confused when they try to use
:documentation without `lexical-binding' turned on.
This thread is a poster child for such confusion.

Is the aim to cause such bother intentionally, to
get users looking into discovering why the gotcha,
and thus discover (and use) `lexical-binding'?
Or is this bug/bother for users really just a case
of "not bothering" to DTRT?

Either way, it seems like this should be fixed,
preferably sooner rather than later.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> As the examples in this thread indicate, users will
> be mightily confused when they try to use
> :documentation without `lexical-binding' turned on.

Yes, I blame this on the use of the old dialect.

> Either way, it seems like this should be fixed,
> preferably sooner rather than later.

It's been fixed progressively since the introduction of this feature
(back in Emacs-25) by dropping the old dialect little by little ;-)


        Stefan

RE: [External] : Supplying DOC string in a `defun' using `defvar'

[Drew Adams]

> > Either way, it seems like this should be fixed,
> > preferably sooner rather than later.
> 
> It's been fixed progressively since the introduction of this feature
> (back in Emacs-25) by dropping the old dialect little by little ;-)

As I'm sure you know, by "this should be fixed"
I meant please fix :documentation, so it works
with both "dialects".

The "fix" of introducing broken stuff, and
saying "It'll all be fixed when the dynamic
dialect finally goes away" doesn't cut the
mustard.  That's just "Demain on rase gratis !".

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> As I'm sure you know, by "this should be fixed"
> I meant please fix :documentation, so it works
> with both "dialects".

Patch welcome.

> The "fix" of introducing broken stuff, and saying "It'll all be fixed
> when the dynamic dialect finally goes away" doesn't cut the mustard.
> That's just "Demain on rase gratis !".

The fact is: the two dialects *are* different and that's the price that
had to be paid in order to introduce lexical scoping without breaking
all the existing code.

The fact that `:documentation` only works in the new dialect is the
least common hurdle among several others (I've already seen at least 20
cases here on gnu.emacs.help (plus at least the same amount in other
places) of ELisp snippets working only in the new dialect and users
stumbling because of that, this is the first that involves the obscure
`:documentation` feature).

So, while it is technically possible to make :documentation work in the
old dialect, it won't fix the core problem nor its most common
manifestations.  That core problem can only be fixed by helping people
move to the new dialect as quickly as possible so we can go back to
living in a single dialect.

This discussion has already helped one user change its code to the new
dialect, so maybe the fact that `:documentation` doesn't work in the old
dialect should be seen as a feature to help people move to the
new dialect.


        Stefan

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Michael Heerdegen]

Christopher Dimech <dimech@gmx.com> writes:

> And change it to what???  That is the whole point.  I installed Emacs 28  
> and need to know how to do things for Emacs 28.  If you want the new dialect
> why not use lexical binding by default?

AFAIK one reason is that this would potentially break hundreds or
thousands of files out there written in the dynamically binding dialect,
lots of them unmaintained.

Michael.

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 10:39 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Drew Adams" <drew.adams@oracle.com>
> Cc: "Christopher Dimech" <dimech@gmx.com>, "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > As I'm sure you know, by "this should be fixed"
> > I meant please fix :documentation, so it works
> > with both "dialects".
>
> Patch welcome.
>
> > The "fix" of introducing broken stuff, and saying "It'll all be fixed
> > when the dynamic dialect finally goes away" doesn't cut the mustard.
> > That's just "Demain on rase gratis !".
>
> The fact is: the two dialects *are* different and that's the price that
> had to be paid in order to introduce lexical scoping without breaking
> all the existing code.
>
> The fact that `:documentation` only works in the new dialect is the
> least common hurdle among several others (I've already seen at least 20
> cases here on gnu.emacs.help (plus at least the same amount in other
> places) of ELisp snippets working only in the new dialect and users
> stumbling because of that, this is the first that involves the obscure
> `:documentation` feature).
>
> So, while it is technically possible to make :documentation work in the
> old dialect, it won't fix the core problem nor its most common
> manifestations.  That core problem can only be fixed by helping people
> move to the new dialect as quickly as possible so we can go back to
> living in a single dialect.
>
> This discussion has already helped one user change its code to the new
> dialect, so maybe the fact that `:documentation` doesn't work in the old
> dialect should be seen as a feature to help people move to the
> new dialect.
>
>
>         Stefan

How long will you allow users to move to the new dialect?  And after that time,
the lexical binding declaration would no longer be necessary, right?

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

Have changed to lexical binding because I find that the :documentation strategy
offers great capability.

> Sent: Thursday, June 03, 2021 at 10:46 AM
> From: "Michael Heerdegen" <michael_heerdegen@web.de>
> To: help-gnu-emacs@gnu.org
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> Christopher Dimech <dimech@gmx.com> writes:
>
> > And change it to what???  That is the whole point.  I installed Emacs 28
> > and need to know how to do things for Emacs 28.  If you want the new dialect
> > why not use lexical binding by default?
>
> AFAIK one reason is that this would potentially break hundreds or
> thousands of files out there written in the dynamically binding dialect,
> lots of them unmaintained.
>
> Michael.
>
>
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> How long will you allow users to move to the new dialect?

I don't know.  Emacs-24 introduced the new dialect back in 2012.
The conversion of Emacs's own ELisp code was just finished a couple
months ago, so I expect it'll quite a few more years.

> And after that time, the lexical binding declaration would no longer
> be necessary, right?

That's right.  Most likely we'll first have a transition period where
the absence of a lexical-binding declaration will trigger a warning.


        Stefan

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Cc: Christopher Dimech <dimech@gmx.com>,  "help-gnu-emacs@gnu.org"
>  <help-gnu-emacs@gnu.org>
> Date: Wed, 02 Jun 2021 17:26:59 -0400
> 
> > Either way, it seems like this should be fixed,
> > preferably sooner rather than later.
> 
> It's been fixed progressively since the introduction of this feature
> (back in Emacs-25) by dropping the old dialect little by little ;-)

Yes, but in case I wasn't clear, it SHOULD be fixed!  Just fix it,
would you?  It MUST BE FIXED!

Did I already say it should be fixed?

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Stefan Monnier <monnier@iro.umontreal.ca> [2021-06-03 01:40]:
> So, while it is technically possible to make :documentation work in the
> old dialect, it won't fix the core problem nor its most common
> manifestations.  That core problem can only be fixed by helping people
> move to the new dialect as quickly as possible so we can go back to
> living in a single dialect.
> 
> This discussion has already helped one user change its code to the new
> dialect, so maybe the fact that `:documentation` doesn't work in the old
> dialect should be seen as a feature to help people move to the
> new dialect.

The purpose of a function would be for example to change the
documentation string.

Purpose of a single function should not be to teach users whatever
dialect, etc.

That is not programming language any more, it is capricious
manipulation of programmers.

It is dark pattern by definition. See:
https://en.wikipedia.org/wiki/Dark_pattern and it uses shame or
invalidation of programmers who use dynamic bindings to force them to
use lexical bindings.

It is something we don't do in free software. I hope this remains as
isolated case in Emacs Lisp.

There are better places to explain programming paradigms than in the
hidden features of the programming language.

Btw. Emacs Lisp can function just well (and so do large Emacs Lisp
packages) and you already confirmed that dynamic binding cannot just
disappear.

Then instead of providing good references how to program "proper" with
lexical bindings, messages come across like dynamic binding is some
kind of a witch and we should be witch hunting it and there is
impression that new functions will be developed to manipulate users to
conform to those views.

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Christopher Dimech <dimech@gmx.com> [2021-06-03 01:57]:
> Have changed to lexical binding because I find that the
> :documentation strategy offers great capability.

Personal experience:

- before lexical bindings all my software functioned well, and I had
  no problems whatsoever; I did not think about it, it did not
  practically bother me;

  Problems were more or less cosmetical, and through discussions I
  could learn only that I could easier find some errors, missing
  variables, unused variables and similar if lexical binding is turned
  on and if I follow the workflow to find such issues. In the end
  compiler warnings are those which are helping me find issues.

Thus my workflow now is following:

1. modify the program;

2. M-x emacs-lisp-byte-compile or
2. M-x emacs-lisp-byte-compile-and-load, as that gives clues by byte
   compiler if there is any problem. Issues are solved at this step. 

3. Press a key for revision control record. In my case the program is
   recorded in the database and new version number is raised. That
   makes program ready to be installed.

4. M-x package-install-from-buffer or package-install-file, as this
   command may give me more clues if there is any problem.

5. Later would come testing with emacs -Q and or with other Emacs
   versions.

And I have a package as RCD Template Interpolation System for Emacs
https://hyperscope.link/3/7/1/3/3/RCD-Template-Interpolation-System-for-Emacs.html

that is separate package because I keep it dynamically not lexically,
with intention. It is used in business to personalize emails and
communication, like yesterday 756 times. There is no lexical bindings
involved and currently I don't know how would I implement it with
lexical bindings involved. I hope dynamic bindings will never go.

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Lars Ingebrigtsen]

Eli Zaretskii <eliz@gnu.org> writes:

> Yes, but in case I wasn't clear, it SHOULD be fixed!  Just fix it,
> would you?  It MUST BE FIXED!

(:documentation foo)

in defuns isn't an official feature, and I don't think it should be,
either.  If we want to provide a feature for doing something like this,
it should be via a (declare (documentation ...)) or something like that.

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

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Eduardo Ochs]

On Thu, 3 Jun 2021 at 03:52, Jean Louis <bugs@gnu.support> wrote:
>
> And I have a package as RCD Template Interpolation System for Emacs
> https://hyperscope.link/3/7/1/3/3/RCD-Template-Interpolation-System-for-Emacs.html
>
> that is separate package because I keep it dynamically not lexically,
> with intention. It is used in business to personalize emails and
> communication, like yesterday 756 times. There is no lexical bindings
> involved and currently I don't know how would I implement it with
> lexical bindings involved. I hope dynamic bindings will never go.


Me too.

I use - zillions of times a day - a template function that is
intrinsically incompatible with lexical binding - this one:

  http://angg.twu.net/eev-current/eev-template0.el.html

and I believe that dynamic binding is much easier to understand and to
explain than lexical binding... also, I interact with beginners a lot,
and currently what I say to them is: "learn dynamic binding first,
even though it is being sort of deprecated, and don't try to use
lexical binding until you have at least one week of experience with
Emacs Lisp... after that you'll be able to compare the two and lexical
binding will make much more sense".

I really hope that people realize the dynamic binding is great as an
educational tool, and that they will keep it available forever, with
all the adequate warnings and caveats - "for the sake of the
secretaries"... see:

  https://www.gnu.org/software/emacs/emacs-paper.html#SEC29

Cheers,
  Eduardo Ochs
  http://angg.twu.net/#eev

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Jean Louis]

* Eduardo Ochs <eduardoochs@gmail.com> [2021-06-03 10:24]:
> On Thu, 3 Jun 2021 at 03:52, Jean Louis <bugs@gnu.support> wrote:
> >
> > And I have a package as RCD Template Interpolation System for Emacs
> > https://hyperscope.link/3/7/1/3/3/RCD-Template-Interpolation-System-for-Emacs.html
> >
> > that is separate package because I keep it dynamically not lexically,
> > with intention. It is used in business to personalize emails and
> > communication, like yesterday 756 times. There is no lexical bindings
> > involved and currently I don't know how would I implement it with
> > lexical bindings involved. I hope dynamic bindings will never go.
> 
> 
> Me too.
> 
> I use - zillions of times a day - a template function that is
> intrinsically incompatible with lexical binding - this one:
> 
>   http://angg.twu.net/eev-current/eev-template0.el.html
> 
> and I believe that dynamic binding is much easier to understand and to
> explain than lexical binding... also, I interact with beginners a lot,
> and currently what I say to them is: "learn dynamic binding first,
> even though it is being sort of deprecated, and don't try to use
> lexical binding until you have at least one week of experience with
> Emacs Lisp... after that you'll be able to compare the two and lexical
> binding will make much more sense".
> 
> I really hope that people realize the dynamic binding is great as an
> educational tool, and that they will keep it available forever, with
> all the adequate warnings and caveats - "for the sake of the
> secretaries"... see:
> 
>   https://www.gnu.org/software/emacs/emacs-paper.html#SEC29

From same document:
https://www.gnu.org/software/emacs/emacs-paper.html#SEC17

It is not necessary for dynamic scope to be the only scope rule
provided, just useful for it to be available.

(defun foo1 (x) (foo2))
(defun foo2 () (+ x 5))
(foo1 1) ⇒ 6
(foo2)

More information from the same document:

Formal Parameters Cannot Replace Dynamic Scope

Some language designers believe that dynamic binding should be
avoided, and explicit argument passing should be used instead. Imagine
that function A binds the variable FOO, and calls the function B,
which calls the function C, and C uses the value of FOO. Supposedly A
should pass the value as an argument to B, which should pass it as an
argument to C.

This cannot be done in an extensible system, however, because the
author of the system cannot know what all the parameters will
be. Imagine that the functions A and C are part of a user extension,
while B is part of the standard system. The variable FOO does not
exist in the standard system; it is part of the extension. To use
explicit argument passing would require adding a new argument to B,
which means rewriting B and everything that calls B. In the most
common case, B is the editor command dispatcher loop, which is called
from an awful number of places.

What's worse, C must also be passed an additional argument. B doesn't
refer to C by name (C did not exist when B was written). It probably
finds a pointer to C in the command dispatch table. This means that
the same call which sometimes calls C might equally well call any
editor command definition. So all the editing commands must be
rewritten to accept and ignore the additional argument. By now, none
of the original system is left!

-- 
Jean

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

Sign an open letter in support of Richard M. Stallman
https://stallmansupport.org/

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Thursday, June 03, 2021 at 11:11 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Drew Adams" <drew.adams@oracle.com>, "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > How long will you allow users to move to the new dialect?
>
> I don't know.  Emacs-24 introduced the new dialect back in 2012.
> The conversion of Emacs's own ELisp code was just finished a couple
> months ago, so I expect it'll quite a few more years.

Let's make it two years.

> > And after that time, the lexical binding declaration would no longer
> > be necessary, right?
>
> That's right.  Most likely we'll first have a transition period where
> the absence of a lexical-binding declaration will trigger a warning.
>
>
>         Stefan
>
>

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

Lars mentioned that although using :documentation works, "(:documentation <foo>)" is
a non-standard way of setting things up in contrast to something like
"(declare (documentation ...))"

What do you think?

> Sent: Thursday, June 03, 2021 at 11:11 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Drew Adams" <drew.adams@oracle.com>, "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > How long will you allow users to move to the new dialect?
>
> I don't know.  Emacs-24 introduced the new dialect back in 2012.
> The conversion of Emacs's own ELisp code was just finished a couple
> months ago, so I expect it'll quite a few more years.
>
> > And after that time, the lexical binding declaration would no longer
> > be necessary, right?
>
> That's right.  Most likely we'll first have a transition period where
> the absence of a lexical-binding declaration will trigger a warning.
>
>
>         Stefan
>
>

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Eduardo Ochs]

On Thu, 3 Jun 2021 at 06:22, Jean Louis <bugs@gnu.support> wrote:
>
> From same document:
> https://www.gnu.org/software/emacs/emacs-paper.html#SEC17
>
> It is not necessary for dynamic scope to be the only scope rule
> provided, just useful for it to be available.

Thanks! =)
  E.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> Lars mentioned that although using :documentation works, "(:documentation <foo>)" is
> a non-standard way of setting things up in contrast to something like
> "(declare (documentation ...))"
>
> What do you think?

Most uses of this `:documentation` feature are for dynamically created
functions, and those typically don't use `defun` but something like
`defalias+lambda`.  `declare`, OTOH is a property of `defun` and isn't
supported inside `lambda`, so it's not clear how that could be made
to work.


        Stefan

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Friday, June 04, 2021 at 3:10 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Drew Adams" <drew.adams@oracle.com>, "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > Lars mentioned that although using :documentation works, "(:documentation <foo>)" is
> > a non-standard way of setting things up in contrast to something like
> > "(declare (documentation ...))"
> >
> > What do you think?
>
> Most uses of this `:documentation` feature are for dynamically created
> functions, and those typically don't use `defun` but something like
> `defalias+lambda`.  `declare`, OTOH is a property of `defun` and isn't
> supported inside `lambda`, so it's not clear how that could be made
> to work.
>         Stefan

Would I need to update the :documentation declaration after the transition to default
lexical binding becomes official?

It is acceptable to use the property of `defun` for the documentation.  For anonymous
functions, I do not think one needs elaborate ways to set the documentation - a normal
description is good enough.

Re: [External] : Supplying DOC string in a `defun' using `defvar'

[Stefan Monnier]

> Would I need to update the :documentation declaration after the transition to default
> lexical binding becomes official?

No.

> It is acceptable to use the property of `defun` for the documentation.  For anonymous
> functions, I do not think one needs elaborate ways to set the documentation - a normal
> description is good enough.

Yet it's specifically for those cases that I introduced the
`:documentation` feature.


        Stefan

[External] : Supplying DOC string in a `defun' using `defvar'

[Christopher Dimech]

> Sent: Friday, June 04, 2021 at 3:46 AM
> From: "Stefan Monnier" <monnier@iro.umontreal.ca>
> To: "Christopher Dimech" <dimech@gmx.com>
> Cc: "Drew Adams" <drew.adams@oracle.com>, "help-gnu-emacs@gnu.org" <help-gnu-emacs@gnu.org>
> Subject: Re: [External] : Supplying DOC string in a `defun' using `defvar'
>
> > Would I need to update the :documentation declaration after the transition to default
> > lexical binding becomes official?
>
> No.
>
> > It is acceptable to use the property of `defun` for the documentation.  For anonymous
> > functions, I do not think one needs elaborate ways to set the documentation - a normal
> > description is good enough.
>
> Yet it's specifically for those cases that I introduced the
> `:documentation` feature.
>
>         Stefan

At an operational level, I approve of your approach.  Well done.