bug#6151: mystery arguments of define-minor-mode + describe-function

bug#6151: mystery arguments of define-minor-mode + describe-function

[jidanni]

Some describe-function results add a mystery argument ARG, not visible
in the corresponding lisp code.

Or maybe it is visible, but not to your average reader.

E.g., here's what describe-function says

    longlines-mode is an interactive compiled Lisp function in
    `longlines.el'.

    (longlines-mode &optional ARG)

    Toggle Long Lines mode.
    In Long Lines mode, long lines are wrapped if they extend beyond

And here's where we get placed when clicking on longlines.el above

    ;;;###autoload
    (define-minor-mode longlines-mode
      "Toggle Long Lines mode.
    In Long Lines mode, long lines are wrapped if they extend beyond

bug#6151: mystery arguments of define-minor-mode + describe-function

[Juanma Barranquero]

On Mon, May 10, 2010 at 12:02,  <jidanni@jidanni.org> wrote:

> Some describe-function results add a mystery argument ARG, not visible
> in the corresponding lisp code.
>
> Or maybe it is visible, but not to your average reader.

Among other things, `define-minor-mode' defines a function, in this
case longlines-mode; and that function, like all minor modes, has an
arg to turn it on or off. So it's not `describe-function' which adds a
"mystery argument", but the docstring for the modes, that sometimes
lacks the relevant info.

That said, any Emacs user should be by now used to minor modes having
such an argument...

    Juanma

bug#6151: mystery arguments of define-minor-mode + describe-function

[jidanni]

>>>>> "JB" == Juanma Barranquero <lekktu@gmail.com> writes:
JB> "mystery argument", but the docstring for the modes, that sometimes
JB> lacks the relevant info.

Perhaps an inventory should be made of these defective docstrings, and
then they should be repaired.

JB> That said, any Emacs user should be by now used to minor modes having
JB> such an argument...

I'm the dud-type user sometimes referred to in http://www.useit.com/alertbox/ .

bug#6151: mystery arguments of define-minor-mode + describe-function

[Juanma Barranquero]

On Mon, May 10, 2010 at 12:57,  <jidanni@jidanni.org> wrote:

> Perhaps an inventory should be made of these defective docstrings, and
> then they should be repaired.

There's such an inventory: it is called Emacs bugs list :-)

> I'm the dud-type user sometimes referred to in http://www.useit.com/alertbox/ .

That meaning?

    Juanma

bug#6151: mystery arguments of define-minor-mode + describe-function

[Lennart Borgman]

On Mon, May 10, 2010 at 12:45 PM, Juanma Barranquero <lekktu@gmail.com> wrote:
> On Mon, May 10, 2010 at 12:02,  <jidanni@jidanni.org> wrote:
>
>> Some describe-function results add a mystery argument ARG, not visible
>> in the corresponding lisp code.
>>
>> Or maybe it is visible, but not to your average reader.
>
> Among other things, `define-minor-mode' defines a function, in this
> case longlines-mode; and that function, like all minor modes, has an
> arg to turn it on or off. So it's not `describe-function' which adds a
> "mystery argument", but the docstring for the modes, that sometimes
> lacks the relevant info.


Maybe the define-minor-mode should always add to the docstring that it
is a minor mode and provide links between the minor mod variable and
the minor mode function?

bug#6151: mystery arguments of define-minor-mode + describe-function

[Stefan Monnier]

> Maybe the define-minor-mode should always add to the docstring that it
> is a minor mode and provide links between the minor mod variable and
> the minor mode function?

Yes, it could check the presence of "ARG" in the provided docstring or
something like that and add a standard blurb if the docstring doesn't
already have it.


        Stefan

bug#6151: mystery arguments of define-minor-mode + describe-function

[Lars Magne Ingebrigtsen]

jidanni@jidanni.org writes:

> Some describe-function results add a mystery argument ARG, not visible
> in the corresponding lisp code.
>
> Or maybe it is visible, but not to your average reader.
>
> E.g., here's what describe-function says
>
>     longlines-mode is an interactive compiled Lisp function in
>     `longlines.el'.
>
>     (longlines-mode &optional ARG)
>
>     Toggle Long Lines mode.
>     In Long Lines mode, long lines are wrapped if they extend beyond
>
> And here's where we get placed when clicking on longlines.el above
>
>     ;;;###autoload
>     (define-minor-mode longlines-mode
>       "Toggle Long Lines mode.
>     In Long Lines mode, long lines are wrapped if they extend beyond

I don't see a bug here -- this is how `define-minor-mode' works.

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

bug#6151: mystery arguments of define-minor-mode + describe-function

[Lars Magne Ingebrigtsen]

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

>> Maybe the define-minor-mode should always add to the docstring that it
>> is a minor mode and provide links between the minor mod variable and
>> the minor mode function?
>
> Yes, it could check the presence of "ARG" in the provided docstring or
> something like that and add a standard blurb if the docstring doesn't
> already have it.

Opening a new "wishlist" bug report for this would be appropriate.

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

bug#6151: mystery arguments of define-minor-mode + describe-function

[jidanni]

>>>>> "LMI" == Lars Magne Ingebrigtsen <larsi@gnus.org> writes:
LMI> Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> Maybe the define-minor-mode should always add to the docstring that it
>>> is a minor mode and provide links between the minor mod variable and
>>> the minor mode function?
>> 
>> Yes, it could check the presence of "ARG" in the provided docstring or
>> something like that and add a standard blurb if the docstring doesn't
>> already have it.

LMI> Opening a new "wishlist" bug report for this would be appropriate.
Somebody who understands the issue please do. Even though I was the
submitter, this is all now beyond my comprehension abilities.