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

Message #23 received at 36478 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: Re: Perhaps rearrange *Help* buffer a bit?
Date: Tue, 09 Jul 2019 00:26:29 +0200

Stefan Monnier <monnier <at> iro.umontreal.ca> writes:

> Here's my favorite color: 
> - don't move it to the end, because it's much too far.
> - hide it by default, with some obvious-enough button-like thingy to
>   expand it on demand.
> - maybe the first line could also be moved into this "metadata" block.

A button that says "Technical details..." or something?  Or... a
text-less button would perhaps be better.

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.
---

The "..." after the function call signature could be marked in the link
face, and could expand into:

---
  car is a built-in function in ‘C source code’.
  Probably introduced at or before Emacs version 1.2.
  This function does not change global state, including the match data.
---

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.

> - 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?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Previous Next

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