Re: master 2a7488d: Add support for displaying short documentation for function groups

[Eli Zaretskii]

> From: Lars Ingebrigtsen <larsi@gnus.org>
> Date: Sun, 11 Oct 2020 05:55:23 +0200
> 
> After tinkering with this for a while on a branch, I've now merged the
> shortdoc stuff into the trunk.

Thanks.  I think this is a very useful documentation feature.

Some comments and thoughts:

1) Is "shortdoc" the best name for this?  This is not really some
short form of existing documentation, it is something else.  Unless we
plan to add more similar features, how about "help-func-groups" or
"help-func-summaries" instead?

2) A better name for the shortdoc-display-group command would be
something like describe-function-group or somesuch -- this is
basically a help command.  (And how about adding it to the Help menu?)

3) An apropos-style command regarding the known groups should probably
be added.  As long as the list of the groups is short, just C-h (which
already works) is enough, but that will become inconvenient as the
list grows, I think.

4) Invoking shortdoc-display-group with "file" as the group signals an
error.  Looks like we lack some auto-loading machinery here.

5) Pushing the button with a function name in the group display pops
up the ELisp manual.  I wonder whether this is a good idea: why not
show the full doc string of the function instead?  Come think about
it, why not _insert_ the full doc string right after the function's
signature, in the same buffer, instead of popping up a new buffer?

6) I question the particular faces used for the display.  Do you
really find the gray background to be such a good idea?

7) Loading the entire database of all the groups at once sounds
un-economical, especially if we envision that the groups will grow and
their number will increase.  Should we perhaps have a separate DB file
for each group?

8) The information stored in the group consists of 2 separate parts:

  . the functions that belong to a group
  . the examples of using each function

These 2 are not necessarily tightly coupled, and the examples are
useful on their own right.  For example, should we perhaps make the
examples of using a particular function accessible from the *Help*
buffer that describes that function?  The "group" button is not an
efficient way of seeing those examples because it shows the entire
group, not the function from which we started.

Also, how about some facility to add a description or explanation of
what each example does?  It's IME sub-optimal to expect the reader to
glean that on his/her own just by looking at the call and the result,
especially when there are several non-trivial arguments.

9) Do we really need all the type keywords (:eval, :eg-result, etc.)?
I'm not sure I understand why not just evaluate the example and
produce the result automatically, without all those different types?
E.g., it sounds artificial to me to use :no-eval* to get "[it
depends]", instead of just saying "[it depends]" explicitly.

10) This should be documented in the user manual, as all other Help
commands.