CL function's docstrings

CL function's docstrings

[Juanma Barranquero]

Many cl*.el functions have a mismatch between the real argument names
and the ones used in their docstrings (mostly because many cl
functions do use some kind of old "standardized" naming scheme for
arguments, like cl-env, cl-keys, etc.).

For example, `cl-macroexpand' uses cl-macro and cl-env as arguments,
but FORM and ENVIRONMENT on the docstring. Unfortunately, this makes
`describe-function' less than useful for these functions (and defeats
argument highlighting).

AFAICS, there are four possible answers:

 1) Do nothing. The easier, if uglier, way :)

 2) Change the argument names to match the docstrings.
     Pros: it is the cleaner way.
     Cons: lot of change in the cl* files; less coherence between argument names
     among functions.

 3) Change the docstrings to match the argument names.
     Pro: easy.
     Cons: names are often much less descriptive than the ones already existing.

 4) Add \(fn ARG1 ARG2...) sections to docstrings.
     Pro: better info in `describe-function'; little change (one fn
line + one blank line
     per function's docstring, at most).
     Cons: many functions will need this, and \(fn ARG) forms are
uglier and more
     difficult to maintain.

I personally gravitate towards 2) or 4).

Does anyone else have an opinion about the issue?

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

Re: CL function's docstrings

[Stefan Monnier]

>  2) Change the argument names to match the docstrings.
>      Pros: it is the cleaner way.
>      Cons: lot of change in the cl* files; less coherence between argument
>      names among functions.

Thanks to the wonders of dynamic scoping this actually changes the
semantics subtly.  In most cases you'll never be able to tell the
difference, but when higer-order functions are involved it can be a problem;
so if you do that, be careful.


        Stefan

Re: CL function's docstrings

[Richard Stallman]

     2) Change the argument names to match the docstrings.
	 Pros: it is the cleaner way.
	 Cons: lot of change in the cl* files; less coherence between argument names
	 among functions.

     3) Change the docstrings to match the argument names.
	 Pro: easy.
	 Cons: names are often much less descriptive than the ones already existing.

For each function, it is possible to change the argument names,
the doc string, or both.

How about if you do whatever is best so as to use the best possible names
in each function?

Re: CL function's docstrings

[Juanma Barranquero]

> How about if you do whatever is best so as to use the best possible names
> in each function?

OK. That's even better. assuming there's no interest in maintaining
absolute argument-name consistency between functions (which doesn't
exist now, to be fair).

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

Re: CL function's docstrings

[Kim F. Storm]

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

>>  2) Change the argument names to match the docstrings.
>>      Pros: it is the cleaner way.
>>      Cons: lot of change in the cl* files; less coherence between argument
>>      names among functions.
>
> Thanks to the wonders of dynamic scoping this actually changes the
> semantics subtly.  In most cases you'll never be able to tell the
> difference, but when higer-order functions are involved it can be a problem;
> so if you do that, be careful.

And do _not_ do it before the release!

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: CL function's docstrings

[Juanma Barranquero]

> And do _not_ do it before the release!

Well, changing argument names can be destabilizing. Changing
docstrings certainly is not.

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

Re: CL function's docstrings

[Richard Stallman]

    Thanks to the wonders of dynamic scoping this actually changes the
    semantics subtly.  In most cases you'll never be able to tell the
    difference, but when higer-order functions are involved it can be a problem;
    so if you do that, be careful.

We never told users it was ok to use these as free variables, so we
don't have to worry about that issue.  However, when changing the arg
names of a function in CL that calls other functions in CL, it would
be good to verify that the called functions don't use them as
free variables.

(It would be unclean to use them that way without defvar'ing them.)

Re: CL function's docstrings

[Richard Stallman]

    > How about if you do whatever is best so as to use the best possible names
    > in each function?

    OK. That's even better. assuming there's no interest in maintaining
    absolute argument-name consistency between functions (which doesn't
    exist now, to be fair).

There is no need for "absolute argument-name consistency".
However, coherence between functions is one factor in what
makes any particular argument name better or worse.

Re: CL function's docstrings

[Stefan Monnier]

> We never told users it was ok to use these as free variables, so we
> don't have to worry about that issue.  However, when changing the arg
> names of a function in CL that calls other functions in CL, it would
> be good to verify that the called functions don't use them as
> free variables.

> (It would be unclean to use them that way without defvar'ing them.)

Defvaring is not necessary in cases such as:

   (let ((nondefvarred-variable 0))
     (mapcar* (lambda (x) (incf nondefvarred-variable))
              somelist))


-- Stefan

Re: CL function's docstrings

[Juanma Barranquero]

> However, coherence between functions is one factor in what
> makes any particular argument name better or worse.

Sure, of course. That's why I said "absolute".

Anyway, as I share Kim's (and others') worries about even small
changes during a freeze (other than cosmetic, like docstring fixes,
obsolescence declarations, substituting an aliased function with the
original, etc.), I think the best plan is:

 - Use "\(fn ARG1 ARG2...)" now (so 22.1 at least has good cl docstrings)
 - Use the best method available, once we branch 22.1

That represents doing twice the fixing, but I don't mind, and it'll
get us the best results (assuming I don't screw up the docstrings :)

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

Re: CL function's docstrings

[Richard Stallman]

     - Use "\(fn ARG1 ARG2...)" now (so 22.1 at least has good cl docstrings)
     - Use the best method available, once we branch 22.1

    That represents doing twice the fixing, but I don't mind, and it'll
    get us the best results (assuming I don't screw up the docstrings :)

I would not have gone to this extra trouble myself, but you can
if you want.