emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

documenting CL functions which accept keyword arguments


From: MON KEY
Subject: documenting CL functions which accept keyword arguments
Date: Fri, 14 Jan 2011 15:04:12 -0500

documenting CL functions which accept keywords

I noticed this afternoon that if I modify the docstring of a CL
function which supports keywords I can get `describe-function' to
return/display its calling convention with what is IMHO a more
palpable presentation. In particular, the modification produces a more
informative function signature in *Help* from:

 (reduce function seq [keyword value]...)

to:

 (reduce function seq &key start end from-end initial-value key)

this is accomplished by modifying the dostring of `reduce' in
emacs-lisp/cl-seq.el's by changing its magic "\(fn ... " line and
upcasing the keywords such that instead of:

(get 'reduce 'function-documentation)

=> "Reduce two-argument FUNCTION across SEQ.

Keywords supported:  :start :end :from-end :initial-value :key

(fn FUNCTION SEQ [KEYWORD VALUE]...)"

(put 'reduce 'function-documentation
 "Reduce two-argument FUNCTION across SEQ.
\nKeywords supported:  :START :END :FROM-END :INITIAL-VALUE :KEY
\n\(fn FUNCTION SEQ &key START END FROM-END INITIAL-VALUE KEY\)")

(get 'reduce 'function-documentation)

=> "Reduce two-argument FUNCTION across SEQ.

Keywords supported:  :START :END :FROM-END :INITIAL-VALUE :KEY

(fn FUNCTION SEQ &key START END FROM-END INITIAL-VALUE KEY)"

One benefit of such modification is that "*Help*" can now font-lock
supported keywords when presenting the docstrings.

Following forms illustrate the displayed return values for the CL
`reduce' function in both vanilla and modified formats with the
`help-downcase-arguments' variable both t and nil for each.

Beneath each line of the displayed return value I've indicated with
!----!  where there is a face text-property with `help-argument-name'
value.

- Vanilla `reduce' docstring with `help-downcase-arguments' nil

(let ((help-downcase-arguments nil))
     (describe-function 'reduce))

,----
|
| (reduce FUNCTION SEQ [KEYWORD VALUE]...)
|         !------! !-!  !-----! !---!
| Reduce two-argument FUNCTION across SEQ.
|                     !------!        !-!
| Keywords supported:  :start :end :from-end :initial-value :key
|
`----

- Vanilla `reduce' docstring with `help-downcase-arguments' non-nil

(let ((help-downcase-arguments t))
     (describe-function 'reduce))

,----
|
| (reduce function seq [keyword value]...)
|         !------! !-!  !-----! !---!
| Reduce two-argument function across seq.
|                     !------!        !-!
| Keywords supported:  :start :end :from-end :initial-value :key
|
`----

- Modified `reduce' docstring with `help-downcase-arguments' nil

(let ((help-downcase-arguments nil))
     (describe-function 'reduce))

,----
|
| (reduce FUNCTION SEQ &key START END FROM-END INITIAL-VALUE KEY)
|         !------! !-!      !---! !-! !------! !-----------! !-!
| Reduce two-argument FUNCTION across SEQ.
|                     !------!        !-!
| Keywords supported:  :START :END :FROM-END :INITIAL-VALUE :KEY
|                       !---!  !-!  !------!  !-----------!  !-!
`----

- Modified `reduce' docstring with `help-downcase-arguments' non-nil

(let ((help-downcase-arguments t))
     (describe-function 'reduce))

,----
|
| (reduce function seq &key start end from-end initial-value key)
|         !------! !-!      !---! !-! !------! !-----------! !-!
| Reduce two-argument function across seq.
|                     !------!        !-!
| Keywords supported:  :start :end :from-end :initial-value :key
|                       !---!  !-!  !------!  !-----------!  !-!
`----

Note also that in the modified docstring *Help* is able to display an
"&key" in the function signature. This display is more in keeping with
the presentation of docstrings for user defined functions which use CL
`destructuring-bind' or `defun*'/`defmacro*' with &key parameters,
e.g. `cvs-mode-marked', `make-vc-bzr-extra-fileinfo',
`define-ibuffer-column', `ebrowse-view/find-class-declaration' etc.

If *Help* can display &key in the argument signature for non-CL
functions and macros it ought to also do so for those functions
defined in the CL files as well.

Are there good reasons why the illustrated modifications should not
appear in docstrings of those CL functions which support keywords?

If not I would like to propose that they be changed.

It would seem that the lisp manual is already in agreement:

,---- (info "(elisp) Function Documentation")
|
| The calling convention specified in this way appears in help
| messages in place of the one derived from the actual arguments of
| the function.
|
| This feature is particularly useful for macro definitions, since the
| arguments written in a macro definition often do not correspond to
| the way users think of the parts of the macro call.
|
`----

--
/s_P\



reply via email to

[Prev in Thread] Current Thread [Next in Thread]