CL function's docstrings

[Juanma Barranquero <lekktu@gmail.com>]

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