Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Robert Pluim]

>>>>> On Thu, 31 Mar 2022 07:38:39 -0400 (EDT), Lars Ingebrigtsen <larsi@gnus.org> said:

    Lars> @@ -1098,7 +1098,7 @@ MET-NAME is as returned by `cl--generic-load-hist-format'."
    Lars>          (dolist (method (cl--generic-method-table generic))
    Lars>            (let* ((info (cl--generic-method-info method)))
    Lars>              ;; FIXME: Add hyperlinks for the types as well.
    Lars> -            (insert (format "%s%S" (nth 0 info) (nth 1 info)))
    Lars> +            (insert (format "%s%S" (nth 0 info) (cons function (nth 1 info))))

Is it worth applying `upcase' to the (nth 1 info) so the result looks
more like C-h f output?

Robert
-- 

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Stefan Monnier]

>     Lars> @@ -1098,7 +1098,7 @@ MET-NAME is as returned by `cl--generic-load-hist-format'."
>     Lars>          (dolist (method (cl--generic-method-table generic))
>     Lars>            (let* ((info (cl--generic-method-info method)))
>     Lars>              ;; FIXME: Add hyperlinks for the types as well.
>     Lars> -            (insert (format "%s%S" (nth 0 info) (nth 1 info)))
>     Lars> +            (insert (format "%s%S" (nth 0 info) (cons function (nth 1 info))))
>
> Is it worth applying `upcase' to the (nth 1 info) so the result looks
> more like C-h f output?

If so, we should be careful to only apply it to the argnames but not to
the specializers since these are case sensitive.

The above patch also leads to odd results for methods with qualifiers.
E.g. `C-h o cl-generic-generalizers RET` shows things like:

    :extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.

    Undocumented

which I find rather confusing.  I understand the motivation for the
change, but I'm not sure it's an improvement.
(and I don't know what would be a good way to combine the qualifiers
with the function name).


        Stefan

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Lars Ingebrigtsen]

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

>> Is it worth applying `upcase' to the (nth 1 info) so the result looks
>> more like C-h f output?
>
> If so, we should be careful to only apply it to the argnames but not to
> the specializers since these are case sensitive.

Yup.  But, yes, I think it would make sense to upcase/italicize the
argnames, because that would clarify what we're talking about here
(which isn't at all obvious).  Patches welcome.

> The above patch also leads to odd results for methods with qualifiers.
> E.g. `C-h o cl-generic-generalizers RET` shows things like:
>
>     :extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.
>
>     Undocumented
>
> which I find rather confusing.

I've now made those things display as before, but I think it's not quite
clear what that part is trying to express, so some clarification here
would be nice.

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

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Stefan Monnier]

>> If so, we should be careful to only apply it to the argnames but not to
>> the specializers since these are case sensitive.
> Yup.  But, yes, I think it would make sense to upcase/italicize the
> argnames, because that would clarify what we're talking about here
> (which isn't at all obvious).  Patches welcome.

Agreed.

>> The above patch also leads to odd results for methods with qualifiers.
>> E.g. `C-h o cl-generic-generalizers RET` shows things like:
>>
>>     :extra "cl-struct" (cl-generic-generalizers type) in ‘cl-generic.el’.
>>
>>     Undocumented
>>
>> which I find rather confusing.
>
> I've now made those things display as before, but I think it's not quite
> clear what that part is trying to express, so some clarification here
> would be nice.

The new behavior is weird/confusing.  I get (with manual
capitalization, while we wait for an actual patch):

    [...]

    (cl-generic-generalizers (SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.

    Support for (derived-mode MODE) specializers.
    Used internally for the (major-mode MODE) context specializers.

    :extra "typeof" (TYPE) in ‘cl-generic.el’.

    [...]

The presence/absence of `cl-generic-generalizers` looks rather
accidental/unexplained (IOW looks like a bug to me :-)

For reference, these correspond to:

    (cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))

and

    (cl-defmethod cl-generic-generalizers :extra "typeof" (type)

in the source code.


        Stefan

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Lars Ingebrigtsen]

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

>     Used internally for the (major-mode MODE) context specializers.
>
>     :extra "typeof" (TYPE) in ‘cl-generic.el’.
>
>     [...]
>
> The presence/absence of `cl-generic-generalizers` looks rather
> accidental/unexplained (IOW looks like a bug to me :-)

I don't think it's more confusing than before, though.  :-/

> For reference, these correspond to:
>
>     (cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))
>
> and
>
>     (cl-defmethod cl-generic-generalizers :extra "typeof" (type)
>
> in the source code.

I think the :extra thing should also be formatted as they're supposed to
be used in code.  (And I really have no idea what that's supposed to
be.)

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

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Stefan Monnier]

Lars Ingebrigtsen [2022-04-02 16:41:36] wrote:
> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>>     Used internally for the (major-mode MODE) context specializers.
>>
>>     :extra "typeof" (TYPE) in ‘cl-generic.el’.
>>
>>     [...]
>>
>> The presence/absence of `cl-generic-generalizers` looks rather
>> accidental/unexplained (IOW looks like a bug to me :-)
>
> I don't think it's more confusing than before, though.  :-/

Before your recent changes it was:

    [...]

    ((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.

    Support for (derived-mode MODE) specializers.
    Used internally for the (major-mode MODE) context specializers.

    :extra "typeof" (TYPE) in ‘cl-generic.el’.

    [...]

So the text matched the part after `(cl-defmethod cl-generic-generalizers`
in the source code:

    (cl-defmethod cl-generic-generalizers ((specializer (head derived-mode))))
and
    (cl-defmethod cl-generic-generalizers :extra "typeof" (type)

Maybe a way to solve the problem is to use something like:

    [...]

    (cl-generic-generalizers (SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.

    Support for (derived-mode MODE) specializers.
    Used internally for the (major-mode MODE) context specializers.

    (cl-generic-generalizers TYPE) in ‘cl-generic.el’.
    :extra "typeof"

    [...]

Of course the `cl-generic-generalizers` is always redundant and risks
pushing the line length past the window width, which was some of the
reasons why I originally used just:

    [...]

    ((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.

    Support for (derived-mode MODE) specializers.
    Used internally for the (major-mode MODE) context specializers.

    :extra "typeof" (TYPE) in ‘cl-generic.el’.

    [...]


-- Stefan

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Lars Ingebrigtsen]

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

>> I don't think it's more confusing than before, though.  :-/
>
> Before your recent changes it was:
>
>     [...]
>
>     ((SPECIALIZER (head derived-mode))) in ‘cl-generic.el’.
>
>     Support for (derived-mode MODE) specializers.
>     Used internally for the (major-mode MODE) context specializers.
>
>     :extra "typeof" (TYPE) in ‘cl-generic.el’.

And I found that very confusing -- I didn't really know what it was
trying to express before this bug report.

> Maybe a way to solve the problem is to use something like:
>
>     [...]
>
>     (cl-generic-generalizers (SPECIALIZER (head derived-mode))) in
> ‘cl-generic.el’.
>
>     Support for (derived-mode MODE) specializers.
>     Used internally for the (major-mode MODE) context specializers.
>
>     (cl-generic-generalizers TYPE) in ‘cl-generic.el’.
>     :extra "typeof"

I still don't understand what the :extra "typeof" is trying to tell me.
:-) 

> Of course the `cl-generic-generalizers` is always redundant and risks
> pushing the line length past the window width, which was some of the
> reasons why I originally used just:

We could format this better, yes.

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

Re: master af0ea35ea0: Tweak how functions are formatted in Implementation in *Help*

[Stefan Monnier]

>>     (cl-generic-generalizers TYPE) in ‘cl-generic.el’.
>>     :extra "typeof"
>
> I still don't understand what the :extra "typeof" is trying to tell me.
> :-)

Not sure what we can do about it, tho.  It's not like qualifiers (which
are what those things are) are self evident if you don't know
about them, indeed.

This is compounded by the fact that this particular qualifier is
specific to ELisp (the more usual qualifiers are `:after`, `:before`,
and `:around`).


        Stefan