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: Drew Adams <drew.adams <at> oracle.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Stefan Monnier <monnier <at> iro.umontreal.ca>
Cc: bug#36478 <36478 <at> debbugs.gnu.org>
Subject: bug#36478: Perhaps rearrange *Help* buffer a bit?
Date: Mon, 8 Jul 2019 16:21:52 -0700 (PDT)

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

FWIW, I think I disagree with handling all such
"metadata" equally, e.g. hiding it all by default.

To me, it makes sense to show, without fishing, that
a function is autoloaded (e.g. not yet loaded),
compiled, etc.; and to show its definition location,
with a link to it; and to show a link to its advice
- especially if the advice changes the doc (which is
what the help is mainly for); and to show a variable's
value.

Such things are helpful for most users, I think, and
they're not in the way.  Such things are not so
concerned with "our" implementation details as they
are with the definition - what the thing is/does.

This is a bit like using `C-u C-x ='.  Both kinds
of help can and do show lots of information.  And
it's not good to overwhelm users at the outset with
too much info, especially in a not-very-organized
way.

But I think that for `*Help*' the info we've long
shown is pretty much user-oriented.  It's more a
question of organization.  I objected, in bug
#36478, to sticking the following kind of info
near the top, before even the first line of the
doc string:

 This function has a compiler macro 'zerop--anon-cmacro'.

Dunno how useful that info is, but a priori that's
not the place to stick it, IMO.  

Many users (I'm one) have no clue what a "compiler
macro" is or why they should care.  (And it's not
explained in the manual, which is a big part of
what bug bu#36478g is about.)

But if that info is actually useful for users (I'm
ignorant, so can't judge that) and if it were put
at or near the end of `*Help*' (and if "compiler
macro" got documented, and especially if those
words linked to the place in the manual where that's
documented), then I'd have no problem with it.

Previous Next

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