mentioning variable aliases in `describe-variable'

mentioning variable aliases in `describe-variable'

[John Paul Wallington]

I think it would be nice to mention when a variable is an alias in
`describe-variable'.  What do people think ?

2002-07-10  John Paul Wallington  <jpw@shootybangbang.com>

	* help-fns.el (describe-variable): Mention if the variable is an
	alias.

Index: help-fns.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/help-fns.el,v
retrieving revision 1.12
diff -u -r1.12 help-fns.el
--- help-fns.el	27 Jun 2002 16:10:23 -0000	1.12
+++ help-fns.el	10 Jul 2002 09:35:23 -0000
@@ -438,7 +438,16 @@
 		(terpri)))
 	    (let ((doc (documentation-property variable 'variable-documentation)))
 	      (princ (or doc "Not documented as a variable.")))
-	  
+	    
+	    ;; Mention if the variable is an alias.
+	    (let ((alias (condition-case nil
+			     (indirect-variable variable)
+			   (error variable))))
+	      (unless (eq alias variable)
+		(terpri)
+		(terpri)
+		(princ (format "This variable is an alias for `%s'." alias))))
+	    
 	    ;; Make a link to customize if this variable can be customized.
 	    ;; Note, it is not reliable to test only for a custom-type property
 	    ;; because those are only present after the var's definition

-- 
John Paul Wallington

Re: mentioning variable aliases in `describe-variable'

[Stefan Monnier]

> I think it would be nice to mention when a variable is an alias in
> `describe-variable'.  What do people think ?

Go for it, although I'd personally put the info near the
first line (as is done for function aliases) rather than near
the bottom.


	Stefan

Re: mentioning variable aliases in `describe-variable'

[John Paul Wallington]

> 
> > I think it would be nice to mention when a variable is an alias in
> > `describe-variable'.  What do people think ?
> 
> Go for it, although I'd personally put the info near the
> first line (as is done for function aliases) rather than near
> the bottom.

I like your suggestion.  How about this:

*** help-fns.el	27 Jun 2002 16:10:23 -0000	1.12
--- help-fns.el	12 Jul 2002 00:10:52 -0000
***************
*** 426,431 ****
--- 426,439 ----
  		(save-excursion
  		  (forward-line -1)
  		  (insert "Automatically becomes buffer-local when set in any fashion.\n"))))
+ 	    ;; mention if it's an alias
+ 	    (let ((alias (condition-case nil
+ 			     (indirect-variable variable)
+ 			   (error variable))))
+ 	      (unless (eq alias variable)
+ 		(princ (format "This variable is an alias for `%s'." alias))
+ 		(terpri)
+ 		(terpri)))
  	    (princ "Documentation:")
  	    (terpri)
  	    (let ((obsolete (get variable 'byte-obsolete-variable)))


It could go underneath the Documentation heading, and it could omit an
alias explictly mentioned in the obsolescence note.  Which is what I
did initially; I was keen on it for twenty minutes or so but rejected
it because alias nature isn't really documentation and
`describe-variable' should spell things out rather than silently omit
information.  I thought I would include it so that someone could
reassure me it is wrong :-)

*** help-fns.el	27 Jun 2002 16:10:23 -0000	1.12
--- help-fns.el	11 Jul 2002 23:34:02 -0000
***************
*** 435,444 ****
  		(princ "; ") (terpri)
  		(princ (if (stringp (car obsolete)) (car obsolete)
  			 (format "use `%s' instead." (car obsolete))))
! 		(terpri)))
  	    (let ((doc (documentation-property variable 'variable-documentation)))
  	      (princ (or doc "Not documented as a variable.")))
! 	  
  	    ;; Make a link to customize if this variable can be customized.
  	    ;; Note, it is not reliable to test only for a custom-type property
  	    ;; because those are only present after the var's definition
--- 435,453 ----
  		(princ "; ") (terpri)
  		(princ (if (stringp (car obsolete)) (car obsolete)
  			 (format "use `%s' instead." (car obsolete))))
! 		(terpri))
! 	      ;; mention if it's an alias, unless the variable it is an alias
! 	      ;; for is already mentioned in the obsolescence note
! 	      (let ((alias (condition-case nil
! 			       (indirect-variable variable)
! 			     (error variable))))
! 		(unless (or (eq alias variable)
! 			    (eq alias (car obsolete)))
! 		  (princ (format "This variable is an alias for `%s'." alias))
! 		  (terpri))))
  	    (let ((doc (documentation-property variable 'variable-documentation)))
  	      (princ (or doc "Not documented as a variable.")))
! 
  	    ;; Make a link to customize if this variable can be customized.
  	    ;; Note, it is not reliable to test only for a custom-type property
  	    ;; because those are only present after the var's definition


-- 
John Paul Wallington

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Fri, 12 Jul 2002 01:30:03 +0100, John Paul Wallington <jpw@shootybangbang.com> wrote:

> I like your suggestion.  How about this:

I like it near the top, too. Much cleaner, IMHO. Also it would make
sense to show the documentation for the aliased variable when describing
the alias. Now, for example:

> automatic-hscrolling's value is t
> 
> Documentation:
> Not documented as a variable.
> 
> This variable is an alias for `auto-hscroll-mode'.
> 
> Defined in `frame'.

but

> auto-hscroll-mode's value is t
> 
> Documentation:
> *Allow or disallow automatic scrolling windows horizontally.
> If non-nil, windows are automatically scrolled horizontally to make
> point visible.
> 
> You can customize this variable.
> 
> Defined in `frame'.

It's not very helpful to mention the aliased variable in the alias
description without the documentation, because that forces the user to
do another describe-variable. And `defvaralias' does not allow
introducing any new documentation for the alias, so there's no
posibility of conflict.

                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[Stefan Monnier]

> It's not very helpful to mention the aliased variable in the alias
> description without the documentation, because that forces the user to
> do another describe-variable. And `defvaralias' does not allow
> introducing any new documentation for the alias, so there's no
> posibility of conflict.

I think that defvaralias should be extended to allow a docstring
(like I just did for defalias) and that the documentation should
be taken either from this docstring or (if there isn't any) from
the alias (as is done for functions).


	Stefan

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Fri, 12 Jul 2002 11:25:33 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> I think that defvaralias should be extended to allow a docstring
> (like I just did for defalias) and that the documentation should
> be taken either from this docstring or (if there isn't any) from
> the alias (as is done for functions).

OK, done.

BTW, defalias' documentation does not mention the DOCSTRING argument.


                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Fri, 12 Jul 2002 11:25:33 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> I think that defvaralias should be extended to allow a docstring
> (like I just did for defalias)

The defalias docstring precludes describe-function from finding the
argument list of built-ins, for example:

ELISP> (defalias 'test 'aref "No doc.")
aref
ELISP> (describe-function 'test)
#("test is an alias for `aref'.\n[Missing arglist.  Please make a bug report.]\n\nNo doc." 0 22 nil 22 26
  (help-args
   (aref)
   category #:help-function-button)
  26 27 nil 27 28 nil 28 29 nil 29 75 nil 75 76 nil 76 83 nil)

because the docstring for the alias does not have "\n\n(function ARGS)"
at the end.

Is that a bug or half a feature? I say "half" because you could do

(defalias 'new-aref
          'aref
          "New documentation.\n\n(aref TABLE INDEX)")

to change the name of the arguments in the alias, and you'll get

> new-aref is an alias for `aref'.
> (aref TABLE INDEX)
> 
> New documentation.

but the name in the argument list must still be the old one.

If it is a bug, AFAICS the only answers are either make `defalias' to
add the arglist to the end of the docstring of aliased built-ins (messy,
I think), or klugde `describe-function' to search the arglist of the
primitive function if the alias has a docstring (ugh).

Or document that you shouldn't add docstrings to aliases for built-ins :)

                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[Richard Stallman]

    If it is a bug, AFAICS the only answers are either make `defalias' to
    add the arglist to the end of the docstring of aliased built-ins (messy,
    I think), or klugde `describe-function' to search the arglist of the
    primitive function if the alias has a docstring (ugh).

At present, only `describe-function' knows how to handle the argument
lists.  For builtin functions, the info is part of the doc string; for
Lisp functions, it is not.  Therefore, for alias functions as well, we
only need `describe-function' to handle the arglist.

Perhaps the best thing is simply to tell the user how to put in the
arglist info when making an alias for a builtin function.  That is
definitely a simple method.

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Tue, 16 Jul 2002 21:04:45 -0600 (MDT), Richard Stallman <rms@gnu.org> wrote:

> Perhaps the best thing is simply to tell the user how to put in the
> arglist info when making an alias for a builtin function.  That is
> definitely a simple method.

I agree; it is much better than doing obscure tricks in `defalias', IMO.
But it'd be also necessary to modify `help-split-fundoc' to allow for a
different function name in the arglist info, so you can say:

(defalias 'get-item
          'aref
          "Return TABLE[INDEX].\n(get-item TABLE INDEX)")

and get the arglist info (now you don't).





                                                           /L/e/k/t/u

arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Stefan Monnier]

> On Tue, 16 Jul 2002 21:04:45 -0600 (MDT), Richard Stallman <rms@gnu.org> wrote:
> 
> > Perhaps the best thing is simply to tell the user how to put in the
> > arglist info when making an alias for a builtin function.  That is
> > definitely a simple method.
> 
> I agree; it is much better than doing obscure tricks in `defalias', IMO.
> But it'd be also necessary to modify `help-split-fundoc' to allow for a
> different function name in the arglist info, so you can say:
> 
> (defalias 'get-item
>           'aref
>           "Return TABLE[INDEX].\n(get-item TABLE INDEX)")
> 
> and get the arglist info (now you don't).

It's definitely on my plan.  This is not just for the case you mention
but because I want to be able to put arglist in the docstring of
autoloaded functions, as well as change defun* to put the original
CL-style arglist in there, so that describe-function would say:

	(foobar ARG1 &key KEY1 (KEY2 default2))
instead of
	(foobar ARG1 &rest --CL21452--)

We just have to decide on a format to use.  The current format for subr's
"arglist in docstring" can be described as "\n\n(<subrname>\\( .*\\)?)\\'".
Using the subroutine's name in there is annoying since it might not
be the same as the symbol the subr is associated with, so the code currently
uses an ugly hack to find the subr's name.  I'm leaning towards allowing
any functions' docstring to end with "\n\n(fn\\( .*\\)?)\\'" instead.
So you'd say

  (defalias 'get-item 'aref "Return TABLE[INDEX].\n\n(fn TABLE INDEX)")

This is pretty easy to implement (I have the code mostly working,
with the only ugliness being "where to put the functions that
insert/extract this arglist info" since they are used by CL, help-fns.el,
eldoc.el, autoload.el, advice.el and maybe more.  I guess the trivial
answer is "in subr.el").

An alternative is to put this info not at the very end, but rather
near the beginning of the docstring.  The reason is that it works
better in the case where someone appends text to the docstring (try
(defadvice car (after foobar activate) 1) and then C-h f car RET
to see what I'm getting at).
Of course, putting it on the first line is probably out because
the first line is handled specially in a few places and it'd be better
not to have to change those.  But maybe we could put it on the
second line such that the regexp would be something like
"\\`.*\nUsage: (fn\\( .*\\)?)$".


	Stefan

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Wed, 17 Jul 2002 09:06:56 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> This is not just for the case you mention
> but because I want to be able to put arglist in the docstring of
> autoloaded functions, as well as change defun* to put the original
> CL-style arglist in there

Very nice.

> This is pretty easy to implement (I have the code mostly working,

Aha, I wondered about "fun" and why DEF was optional in
`help-split-fundoc' :)

> with the only ugliness being "where to put the functions that
> insert/extract this arglist info" since they are used by CL, help-fns.el,
> eldoc.el, autoload.el, advice.el and maybe more.  I guess the trivial
> answer is "in subr.el").

Unless you want to add a new file to lisp/emacs-lisp/. Perhaps we should
create emacs-lisp/doc-helper.el and move some code from help-fns.el.

> An alternative is to put this info not at the very end, but rather
> near the beginning of the docstring.  The reason is that it works
> better in the case where someone appends text to the docstring (try
> (defadvice car (after foobar activate) 1) and then C-h f car RET
> to see what I'm getting at).

But I wonder if there's much code that adds to the docstring of a
function. If advice.el is the exception, we could just adapt it to "skip"
the arglist info.

> But maybe we could put it on the
> second line such that the regexp would be something like
> "\\`.*\nUsage: (fn\\( .*\\)?)$".

Second line sounds too much special-cased to me; I'd rather have it at
the end and modify advice.el than get it from the middle of the
docstring.

Are there other options? Puting text properties in the docstring,
modifying DEFUN, adding a new 'documentation-arglist property, any other?
Perhaps clearly disociating documentation from arglist would be good...


                                                           /L/e/k/t/u

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Stefan Monnier]

> > This is pretty easy to implement (I have the code mostly working,
> Aha, I wondered about "fun" and why DEF was optional in
> `help-split-fundoc' :)

It's just remnants of some of my then-current code.  Nothing really usable.

> > with the only ugliness being "where to put the functions that
> > insert/extract this arglist info" since they are used by CL, help-fns.el,
> > eldoc.el, autoload.el, advice.el and maybe more.  I guess the trivial
> > answer is "in subr.el").
> 
> Unless you want to add a new file to lisp/emacs-lisp/. Perhaps we should
> create emacs-lisp/doc-helper.el and move some code from help-fns.el.

It's at most 50 lines of code.  Hardly worth a separate file.

> > An alternative is to put this info not at the very end, but rather
> > near the beginning of the docstring.  The reason is that it works
> > better in the case where someone appends text to the docstring (try
> > (defadvice car (after foobar activate) 1) and then C-h f car RET
> > to see what I'm getting at).
> 
> But I wonder if there's much code that adds to the docstring of a
> function. If advice.el is the exception, we could just adapt it to "skip"
> the arglist info.

Indeed, whichever way we o, we can always get things right.
But if we can reduce the amount of code necessary to get it right,
I think it's a plus.

> > But maybe we could put it on the
> > second line such that the regexp would be something like
> > "\\`.*\nUsage: (fn\\( .*\\)?)$".
> 
> Second line sounds too much special-cased to me; I'd rather have it at
> the end and modify advice.el than get it from the middle of the
> docstring.

But seen from the point of view of the user writing the docstring
for his alias,

        "This does foo.
      (blabla ARG1 &optional TOTO)
      When ARG1 is non-nil blabla else blibli."

is IMO more readable (in the source code) than

        "This does foo.
      When ARG1 is non-nil blabla else blibli.

      (blabla ARG1 &optional TOTO)"

In any case, I don't care much either way.

> Are there other options? Puting text properties in the docstring,

The docstring is often/mostly extracted from the DOC file or from the .elc
file, so it can't have any text-property (without significant changes).

> modifying DEFUN, adding a new 'documentation-arglist property, any other?

It's good to associate it with the function rather than with the symbol
to which this function is associated, so that if you do
(fset 'foo (symbol-function 'bar)), the info is not lost.  So using
a symbol-property is a bit less attractive.

In the case of autoloaded functions, putting the info in the docstring
means that it quietly sits in the DOC file rather than tying up
real memory.

> Perhaps clearly disociating documentation from arglist would be good...

Yes, of course, but it has its own shortcomings.


	Stefan

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Wed, 17 Jul 2002 10:33:39 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> It's at most 50 lines of code.  Hardly worth a separate file.

Ok, although there are like 73 .el files of < 100 lines already. ;)

> But if we can reduce the amount of code necessary to get it right,
> I think it's a plus.

Of course.

> In any case, I don't care much either way.

Me neither, in fact.

> Yes, of course, but it has its own shortcomings.

Sure. Anyway, you're the expert and obviously you've thought about it
quite a bit.


                                                           /L/e/k/t/u

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Wed, 17 Jul 2002 09:06:56 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> but because I want to be able to put arglist in the docstring of
> autoloaded functions

BTW, it'd be nice to have also a way to make available the obsolescence
info of autoloaded functions. Currently, the obsolescence info
associated via `make-obsolete' and `make-obsolete-variable' is only
available after the function is loaded. That sometimes forces to retain
redundant info, as in `decompose-composite-char':


> decompose-composite-char is an autoloaded Lisp function in `composite'.
> [Arg list not available until function definition is loaded.]
> 
> Convert CHAR to string.
> This is only for backward compatibility with Emacs 20.4 and earlier.

vs.

> decompose-composite-char is a compiled Lisp function in `composite'.
> (decompose-composite-char CHAR &optional TYPE WITH-COMPOSITION-RULE)
> 
> This function is obsolete since 21.1;
> use `char-to-string' instead.
> 
> Convert CHAR to string.
> This is only for backward compatibility with Emacs 20.4 and earlier.



                                                           /L/e/k/t/u

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Stefan Monnier]

> On Wed, 17 Jul 2002 09:06:56 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:
> 
> > but because I want to be able to put arglist in the docstring of
> > autoloaded functions
> 
> BTW, it'd be nice to have also a way to make available the obsolescence
> info of autoloaded functions. Currently, the obsolescence info
> associated via `make-obsolete' and `make-obsolete-variable' is only
> available after the function is loaded. That sometimes forces to retain
> redundant info, as in `decompose-composite-char':

We can/should put a ;;;###autoload cookie on the `make-obsolete' call.


	Stefan

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Wed, 17 Jul 2002 10:31:35 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> We can/should put a ;;;###autoload cookie on the `make-obsolete' call.

Silly me. You're absolutely right.


                                                           /L/e/k/t/u

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Richard Stallman]

    BTW, it'd be nice to have also a way to make available the obsolescence
    info of autoloaded functions.

We could add an extra argument in `autoload' where you can specify
the obsolescence information, and we could perhaps make
update-file-autoloads notice the "obsolete" information
and put that in the `autoload'.

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Thu, 18 Jul 2002 08:55:31 -0600 (MDT), Richard Stallman <rms@gnu.org> wrote:

> We could add an extra argument in `autoload' where you can specify
> the obsolescence information, and we could perhaps make
> update-file-autoloads notice the "obsolete" information
> and put that in the `autoload'.

I thought so too, but Stefan's method is simpler, and there aren't that
many functions that are both autoloaded and obsolete.

Apart from the four or so functions to which I've added autoload cookies,
there's a few (dot, dot-max, dot-min, dot-marker, buffer-flush-undo,
baud-rate, compiled-function-p and define-function) that don't get
obsolescence info when `describe-variable'd because that info is in
emacs-lisp/bytecomp.el but should really be in subr.el (where the
functions are defined).

I have not moved that obsolescence declarations to subr.el because I
don't know enough about the bytecompiler to know if that makes a
difference, but I think no, so if someone-in-the-know gives me the go,
I'll change them ASAP.

                                                           /L/e/k/t/u

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Richard Stallman]

    I have not moved that obsolescence declarations to subr.el because I
    don't know enough about the bytecompiler to know if that makes a
    difference, but I think no, so if someone-in-the-know gives me the go,
    I'll change them ASAP.

It should not matter, but give it a try and see.

Re: arglist in docstring (was: mentioning variable aliases in `describe-variable' )

[Juanma Barranquero]

On Thu, 18 Jul 2002 15:14:28 -0600 (MDT), Richard Stallman <rms@gnu.org> wrote:

> It should not matter, but give it a try and see.

Ok, installed.


                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Thu, 11 Jul 2002 15:25:55 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> Go for it, although I'd personally put the info near the
> first line (as is done for function aliases) rather than near
> the bottom.

And speaking of that: why does `describe-variable' put that useless
"Documentation:" header? `describe-function' does not do it, i.e.:

> auto-save-hook's value is nil
> 
> Documentation:
> Normal hook run just before auto-saving.
> 
> Defined in `files'.

vs.

> assq-delete-all is a compiled Lisp function in `subr'.
> (assq-delete-all KEY ALIST)
> 
> Delete from ALIST all elements whose car is KEY.
> Return the modified alist.



                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[John Paul Wallington]

> And speaking of that: why does `describe-variable' put that useless
> "Documentation:" header? `describe-function' does not do it, i.e.:
> 
> > auto-save-hook's value is nil
> > 
> > Documentation:
> > Normal hook run just before auto-saving.
> > 
> > Defined in `files'.
> 
> vs.
> 
> > assq-delete-all is a compiled Lisp function in `subr'.
> > (assq-delete-all KEY ALIST)
> > 
> > Delete from ALIST all elements whose car is KEY.
> > Return the modified alist.

I think for variables with big values, like `global-map', it makes sense.

-- 
John Paul Wallington

Re: mentioning variable aliases in `describe-variable'

[Miles Bader]

John Paul Wallington <jpw@shootybangbang.com> writes:
> > And speaking of that: why does `describe-variable' put that useless
> > "Documentation:" header? `describe-function' does not do it, i.e.:
> 
> I think for variables with big values, like `global-map', it makes sense.

Why?  If you mean `because it matches the Value: label used below', I'm
not sure why it matters.

I agree with Juanma; `Documentation:' is just an ugly and useless wart.

-Miles
-- 
Is it true that nothing can be known?  If so how do we know this?  -Woody Allen

Re: mentioning variable aliases in `describe-variable'

[John Paul Wallington]

> > > And speaking of that: why does `describe-variable' put that useless
> > > "Documentation:" header? `describe-function' does not do it, i.e.:
> > 
> > I think for variables with big values, like `global-map', it makes sense.
> 
> Why?  If you mean `because it matches the Value: label used below', I'm
> not sure why it matters.
> 
> I agree with Juanma; `Documentation:' is just an ugly and useless wart.

I guess it does look cleaner without it.

-- 
John Paul Wallington

Re: mentioning variable aliases in `describe-variable'

[Juanma Barranquero]

On Fri, 12 Jul 2002 09:47:24 +0100, John Paul Wallington <jpw@shootybangbang.com> wrote:

> I guess it does look cleaner without it.

Even in long variables with the Value: header, IMO.

Any opposition to removing the "Documentation:" header?

                                                           /L/e/k/t/u

Re: mentioning variable aliases in `describe-variable'

[Stefan Monnier]

> John Paul Wallington <jpw@shootybangbang.com> writes:
> > > And speaking of that: why does `describe-variable' put that useless
> > > "Documentation:" header? `describe-function' does not do it, i.e.:
> > 
> > I think for variables with big values, like `global-map', it makes sense.
> 
> Why?  If you mean `because it matches the Value: label used below', I'm
> not sure why it matters.

Maybe because John forgot that when the value is "large" it's moved to
after the documentation ?

> I agree with Juanma; `Documentation:' is just an ugly and useless wart.

Agreed.  While we're at it, I don't like the fact that the
"defined in `foo'" is at the end.  Putting it at the beginning (as is
done for functions) is much better IMO.
I think the general rule-of-thumb is that one-line info should be at the
beginning and large/variable-sized info (such as the doc) should be
kept for the "tail" end.


	Stefan