bug#9115: 24.0.50; `documentation' should not return args list for CL defun*.

[Stefan Monnier]

severity 9115 wishlist
retitle 9115 `documentation' should let you choose whether to include `usage'
thanks

>> (let* ((doc (documentation bidule))
>> (split (help-split-fundoc doc nil)))
>> (if split (cdr split) doc))
> Yes, thanks, that's usable.
> But it add unnecessary complications for same result, so for the moment
> i will use my original code that is simpler and shorter.

Yes, as mentioned earlier, I'm not particularly proud of the gymnastic
you have to go through to get what you want.

>> might work better.  Still, you should be able to get the right code by
>> reading the docstring and trying things out.
> Docstring is hard to understand.
> The term "usage" in docstring is not understandable until trying out the
> function and see results after evaluation.

Ah, I see the problem now.  Would the patch below have helped?

> Idem for "def" argument.

Not sure how I can improve this part.


        Stefan


=== modified file 'lisp/help-fns.el'
--- lisp/help-fns.el    2011-06-28 17:20:41 +0000
+++ lisp/help-fns.el    2011-08-03 14:29:40 +0000
@@ -102,7 +102,8 @@
 
 (defun help-split-fundoc (docstring def)
   "Split a function DOCSTRING into the actual doc and the usage info.
-Return (USAGE . DOC) or nil if there's no usage info.
+Return (USAGE . DOC) or nil if there's no usage info, where USAGE info
+is a string such as \"(apply FUNCTION &rest ARGUMENTS)\".
 DEF is the function whose usage we're looking for in DOCSTRING."
   ;; Functions can get the calling sequence at the end of the doc string.
   ;; In cases where `function' has been fset to a subr we can't search for