pcase documentation missing

pcase documentation missing

[Andy Moreton]

Using "C-h f pcase" in the master branch only displays the docstring
from the pcase macro, but omits the documentation of the pcase
extensions defined with pcase-defmacro.

Evaluating this shows the extension docs can still be computed:
  (require 'pcase)
  (pcase--make-docstring)

Is this expected ?

    AndyM

Re: pcase documentation missing

[Stefan Monnier]

> Using "C-h f pcase" in the master branch only displays the docstring
> from the pcase macro, but omits the documentation of the pcase
> extensions defined with pcase-defmacro.
>
> Evaluating this shows the extension docs can still be computed:
>   (require 'pcase)
>   (pcase--make-docstring)
>
> Is this expected ?

No, sounds like a bug


        Stefan

Re: pcase documentation missing

[Michael Heerdegen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> > Using "C-h f pcase" in the master branch only displays the docstring
> > from the pcase macro, but omits the documentation of the pcase
> > extensions defined with pcase-defmacro.
> >
> > Evaluating this shows the extension docs can still be computed:
> >   (require 'pcase)
> >   (pcase--make-docstring)
> >
> > Is this expected ?
>
> No, sounds like a bug

pcase.el is not loaded after starting emacs -Q, so what you see is the
(static part of the) docstring from the autoload until you load the
library, right?

Michael.

Re: pcase documentation missing

[Stefan Monnier]

> pcase.el is not loaded after starting emacs -Q, so what you see is the
> (static part of the) docstring from the autoload until you load the
> library, right?

Hmm... I thought `C-h f` loaded the file nowadays when displaying the
docstring of an autoloaded function (at least I seem to remember that
we had to do it in order for \\{foo-mode-map} references to work).


        Stefan

Re: pcase documentation missing

[Andy Moreton]

On Thu 21 Feb 2019, Stefan Monnier wrote:

>> pcase.el is not loaded after starting emacs -Q, so what you see is the
>> (static part of the) docstring from the autoload until you load the
>> library, right?
>
> Hmm... I thought `C-h f` loaded the file nowadays when displaying the
> docstring of an autoloaded function (at least I seem to remember that
> we had to do it in order for \\{foo-mode-map} references to work).
>
>
>         Stefan

That seems to be the problem. On the emacs-26 branch and master, from
"emacs -Q" only the static docstring is shown. The dynamically generated
part is only shown after (load-library "pcase") or (require 'pcase) or
evaluating a pcase form.

    AndyM

Re: pcase documentation missing

[Michael Heerdegen]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> Hmm... I thought `C-h f` loaded the file nowadays when displaying the
> docstring of an autoloaded function (at least I seem to remember that
> we had to do it in order for \\{foo-mode-map} references to work).

Seems that this magic is restricted to functions whose docstring
contains a key substitution construct - see `help-enable-auto-load'.


Michael.

Re: pcase documentation missing

[Michael Heerdegen]

Michael Heerdegen <michael_heerdegen@web.de> writes:

> Seems that this magic is restricted to functions whose docstring
> contains a key substitution construct - see `help-enable-auto-load'.

I see Stefan has fixed it.

There is a little part that I don't understand, however: why does C-h f
pcase load radix-tree?

Michael.

Re: pcase documentation missing

[Stefan Monnier]

> There is a little part that I don't understand, however: why does C-h f
> pcase load radix-tree?

Probably for the same reason `C-h f car RET` loads radix-tree?

I know why radix-tree is involved: it's used by describe-function to be
able to complete&find function names of packages that aren't yet loaded.
With some careful coding it should be possible to avoid loading it in
cases where there's no need for completion and where the function is
already defined.

Apparently I wasn't careful enough when I wrote that.


        Stefan

Re: pcase documentation missing

[Michael Heerdegen]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> I know why radix-tree is involved: it's used by describe-function to be
> able to complete&find function names of packages that aren't yet
> loaded.

Ah - ok.  I thought it was somehow because of the radix-tree-leaf
pattern.

> With some careful coding it should be possible to avoid loading it in
> cases where there's no need for completion and where the function is
> already defined.

Doesn't sound like a good investment of your time.


Thanks,

Michael.