() Drew Adams <drew.adams@oracle.com>
() 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:
                              function
                              variable
                              face
                              property
                              ...
                              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