Re: Changes in revision 114466

[Xue Fuqiao <xfq.free@gmail.com>]

On Sun, Sep 29, 2013 at 3:24 PM, Thien-Thi Nguyen <ttn@gnu.org> wrote:
> () Eli Zaretskii <eliz@gnu.org>
> () Sun, 29 Sep 2013 05:36:08 +0300
>
>    > >> +@c FIXME: Document these functions:
>    > >> +@c `bool-vector-exclusive-or'
>    > >> +@c `bool-vector-union'
>    > >> +@c `bool-vector-intersection'
>    > >> +@c `bool-vector-set-difference'
>    > >> +@c `bool-vector-not'
>    > >> +@c `bool-vector-subset'
>    > >> +@c `bool-vector-count-matches'
>    > >> +@c `bool-vector-count-matches-at'
>
>    Nothing to be sorry about, and thank you.
>
> If the names of these functions were produced by some scanning program,
> this is a good opportunity to add that code to the repo (under admin/).
>
> If they were produced by hand, then i guess the zeroth step would be to
> write a program that likewise produces them.
>
> The overall meta-goals are to make doc coverage easy to determine for
> everyone, and to render the selection criteria (for surely, some things
> do not warrant "full" documentation) explicit and consequently subject
> to refinement.
>
> With this in place, the overall goal of improving the doc coverage is
> most easily realizable, not just once, but also as an ongoing basis, as
> Emacs gains new features over time.

Agreed.  The name of these functions were produced by hand.  To make doc
coverage, the only solution that I see is scanning the Emacs repo for
keywords like these:

  (def\\(var\\|const\\|custom\\)
  (def\\(un\\|subst\\|macro\\|advice\\)
  (def\\(type\\|struct\\|class\\|ine-condition\\)
  DEFUN ("
  maybe also for defgroup, defmath, defalias, cl-{defun, defmacro,
defsubst}, ...

although `defadvice' should not be used for Lisp code in Emacs proper.
But I see one problem: not every {functions, variables, ...} needs
documenting.  E.g., some functions/variables use two hyphens to separate
prefix.  These functions/variables usually don't needs documenting.

IMO every user option and every command needs documentation.

-- 
Best regards, Xue Fuqiao.
http://www.gnu.org/software/emacs/