[SciPy-Dev] SciPy Doc "low hanging fruit"

[David Goldsmith]

Hi!  A few days ago I referenced a document I've been preparing roughly
"triaging" the SciPy docstrings; well, I'm done - if you care to view it,
it's here<http://spreadsheets.google.com/ccc?key=0AvCyyT1vWOKJdG5ST2NESTVQWHlFeWMwSmZXd241eFE&hl=en>.
Key: "Empty" = Wiki sees auto-generated content only; "Unsubstantial" >
Empty, but possessing not more than the brief summary, Parameters, and
sometimes Returns, Extended Summary, and perhaps one other, typically
scanty, section; "Substantial" = a lot of content, but flawed in some
fundamental way (e.g., missing an important section, not Standards
compliant); "Ready for Review?" = looks like it might be ready for review,
but I didn't "study" any single docstring, thus the ?; obviously, all but
the first are (perhaps highly) subjective.  Bottom line: docstrings scanned:
2265 (2450 actually, the difference being docstrings for obsolete objects,
which I've already changed to Unimportant status) Empty: 35%, Unsubstantial:
44%, Substantial: 18.5%, Ready for Review?: 2.4% (0.1% rounding error).

So why did I title this email "low hanging fruit"?  Much of both the
Unsubstantial and Substantial content was non-compliant, Standards-wise, and
a simple, easy improvement can be achieved simply by finding these and
making what's already there compliant, and adding correctly ordered headings
for missing (but needed, or likely to be needed) sections.  Low hanging
fruit...

DG
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20100525/ebad536d/attachment.html>