[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Changes in revision 114466

From: Thien-Thi Nguyen
Subject: Re: Changes in revision 114466
Date: Mon, 30 Sep 2013 17:52:18 +0200
User-agent: Gnus/5.13 (Gnus v5.13) Emacs/24.3 (gnu/linux)

() Drew Adams <address@hidden>
() Mon, 30 Sep 2013 08:05:04 -0700 (PDT)

   Having code does not preclude having comments.
   Having comments does not preclude having documentation.

What precludes most results is the right combination of awareness
and effort, which is in YMMV territory.  Which is obvious by:

   [...] From my point of view: [...]

   My (likely lone) opinion remains [...]

It sounds like the scanning program would do well to take options
to control its selectivity, something like:

 -i, --inclusiveness N   -- control what to include in the output;
                            N is an integer from 1 (default) to 5:
                              1 -- "public" funcs, vars
                              2 -- 1 + faces
                              3 -- 2 + properties
                              4 -- 3 + private stuff
                              5 -- everything 

Alternatively, something like:

 -f, --flag ASPECTS      -- include only ASPECTS in output;
                            ASPECTS is a comma-separated list,
                            with elements from:
                              ALL (same as all of the above)
 -p, --private           -- also include "private" elements
                            (those with "--" in their name)

The latter gives more control, which i like, but anyway the point
is to enable those who want to take a bite out of the doc coverage
pie to specify their appetite.  Then, ttn the lazy bum can run it
w/ ‘-f function’ and j.r.motivated-hacker can use ‘-f ALL -p’.

(Of course, what the Official Policy will be is another question.
I think for this effort (increasing doc coverage), if we focus on
clean mechanism, the need for lots of policy discussion will be
reduced -- less need to leave /home, so to speak. :-D)

Thien-Thi Nguyen
   GPG key: 4C807502
   (if you're human and you know it)
      read my lisp: (responsep (questions 'technical)
                               (not (via 'mailing-list)))
                     => nil

Attachment: pgpEVQ5qGh44P.pgp
Description: PGP signature

reply via email to

[Prev in Thread] Current Thread [Next in Thread]