sit-for arg old-nodisp not documented

sit-for arg old-nodisp not documented

[Lennart Borgman]

`sit-for' has an argument old-nodisp that is not described in the doc 
string.

Re: sit-for arg old-nodisp not documented

[Juanma Barranquero]

> `sit-for' has an argument old-nodisp that is not described in the doc
> string.

Not exactly. If you read it again carefully, you'll notice `sit-for'
has two modes of invocation:

  - (modern):  (sit-for SECONDS &optional NODISP)
  - (old): (sit-for SECONDS &optional MILLISECONDS NODISP)

So the function is really defined as

  (sit-for SECONDS &optional NODISP OLD-NODISP)

which is accurate, but does not help argument highlighting
(MILLISECONDS is not highlighted) and does not match the description
(which uses NODISP for the OLD-NODISP argument).

The "correct" thing to do would be to define the function (or at
least, the docstring) as

  (sit-for SECONDS &optional NODISP-OR-MILLISECONDS IGNORED-OR-NODISP)

but that would be ugly.

After the 22.1 release I'll take a deep look at the many docstrings
that still have irregularities which are not easy to resolve. I don't
want to be forced to add "\(fn ...)" sections to more docstrings
(there are already too many, I'd like to remove some), and also don't
want to start changing argument names because of dynamic binding
issues (sometimes is difficult to see whether an argument is used as a
local binding in another function higher in the call stack).

-- 
                    /L/e/k/t/u

Re: sit-for arg old-nodisp not documented

[Lennart Borgman]

Juanma Barranquero wrote:

>>`sit-for' has an argument old-nodisp that is not described in the doc
>>string.
>>    
>>
>
>Not exactly. If you read it again carefully, you'll notice `sit-for'
>has two modes of invocation:
>
>  - (modern):  (sit-for SECONDS &optional NODISP)
>  - (old): (sit-for SECONDS &optional MILLISECONDS NODISP)
>
>So the function is really defined as
>
>  (sit-for SECONDS &optional NODISP OLD-NODISP)
>  
>
Thanks, I did see that (though I am a lousy reader) but OLD-NODISP is 
still not mentioned. An easy way to fix this particular problem would 
perhaps be to just change the description of the old format (since that 
is just a part of the doc string I assume):

  - (old): (sit-for SECONDS &optional MILLISECONDS OLD-NODISP)

Re: sit-for arg old-nodisp not documented

[Juanma Barranquero]

On 7/31/05, Lennart Borgman <lennart.borgman.073@student.lu.se> wrote:

> Thanks, I did see that (though I am a lousy reader) but OLD-NODISP is
> still not mentioned.

It is not mentioned because it is not OLD-NODISP. It is NODISP, when
using the old profile.

> An easy way to fix this particular problem would
> perhaps be to just change the description of the old format (since that
> is just a part of the doc string I assume):
> 
>   - (old): (sit-for SECONDS &optional MILLISECONDS OLD-NODISP)

That would not help argument highlighting (the second declaration
won't be used to detect argument references in the docstring), and you
will need to add a section explaining what OLD-NODISP do. As it is
now, it is clear that MILLISECONDS is an additional argument that just
happens to be between SECONDS and NODISP.

-- 
                    /L/e/k/t/u

Re: sit-for arg old-nodisp not documented

[Lennart Borgman]

Juanma Barranquero wrote:

>>An easy way to fix this particular problem would
>>perhaps be to just change the description of the old format (since that
>>is just a part of the doc string I assume):
>>
>>  - (old): (sit-for SECONDS &optional MILLISECONDS OLD-NODISP)
>>    
>>
>
>That would not help argument highlighting (the second declaration
>won't be used to detect argument references in the docstring), and you
>will need to add a section explaining what OLD-NODISP do. As it is
>now, it is clear that MILLISECONDS is an additional argument that just
>happens to be between SECONDS and NODISP.
>  
>
I just meant that the old declaration could perhaps be an implicit 
description.

Re: sit-for arg old-nodisp not documented

[Juanma Barranquero]

On 7/31/05, Lennart Borgman <lennart.borgman.073@student.lu.se> wrote:

> I just meant that the old declaration could perhaps be an implicit
> description.

I don't understand.

Just say what changes would you do to the docstring, and if they're
good, by all means commit them.

-- 
                    /L/e/k/t/u

Re: sit-for arg old-nodisp not documented

[Lennart Borgman]

Juanma Barranquero wrote:

>On 7/31/05, Lennart Borgman <lennart.borgman.073@student.lu.se> wrote:
>
>  
>
>>I just meant that the old declaration could perhaps be an implicit
>>description.
>>    
>>
>
>I don't understand.
>
>Just say what changes would you do to the docstring, and if they're
>good, by all means commit them.
>
I guess I just notice too much details sometimes ;-)  But anyhow maybe 
it is better just to add a last line instead of my first suggestion 
which obviously was not as clear:

   OLD-NODISP is just a placeholder making it possible to still use 
`defadvice' on the old form.

There is a comment in the code which I think means this.

Re: sit-for arg old-nodisp not documented

[Richard M. Stallman]

    `sit-for' has an argument old-nodisp that is not described in the doc 
    string.

We often don't document an argument that we don't encourage people to
use.