GNU bug report logs - #36478
26.2; Doc strings with "This function has a compiler macro..." and "This function does not change global state"

Previous Next

Full log

View this message in rfc822 format

From: Stefan Monnier <monnier <at> iro.umontreal.ca>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: bug#36478: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 08 Jul 2019 19:30:21 -0400

> To take the `car' example again:
>
> ---
> (car LIST) ...
>
> Return the car of LIST.  If arg is nil, return nil.
> Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
>
> See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
> Lisp concepts such as car, cdr, cons cell and list.
> ---

Sounds about right, yes.  I think I'd vote to keep the function/macro
distinction displayed by default at least (and maybe function/command as
well).  Maybe simply as

    Function: (car LIST) ...
    
    Return the car of LIST.  If arg is nil, return nil.
    Error if arg is not nil and not a cons cell.  See also ‘car-safe’.
    
    See Info node ‘(elisp)Cons Cells’ for a discussion of related basic
    Lisp concepts such as car, cdr, cons cell and list.

> And `car' in the signature could be a link to the source code, as the
> "C source code" is now, so you don't have to expand the details to get
> to the link.

Sounds good.

>> - These *Help* buffers would benefit from a bit of face-lift (e.g. put
>>   a different face on the metadata part, yet another on the
>>   calling-convention example, ...).
> The parameters are in an italic face...  If we're hiding the details,
> perhaps a special face for the details isn't necessary?

Maybe you're right.  Then again, I think it's worth keeping the block
highlighted somehow to clearly indicate the difference between the
docstring and the auto-generated metadata, maybe with a discreet
background color.


        Stefan

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.