[Doc-SIG] Docstring Standards

[Tony J Ibbs (Tibs)]

Hmm. I'm not *entirely* convinced that formal semantics for how to
present argument list documentation, etc., is a Good Thing, even though
I believe I've argued for "data mining" of docstrings in the past.

On the "for" side, the work I'm currently doing on embedding Java in our
product, and automatically wrapping pre-existing C functions as Java
methods, would be a lot harder if we had *not* had a fairly formal
requirement on C function documentation (including documenting if each
argument is in, out or both). Of course, that same requirement also
means a lot of redundant text in the documentation produced.

However, on the "against" side, looking at javadoc guidelines seems (to
me) to show a tendency to ask for over-documentation of parameters,
return values, etc. - rather on the grounds that the "interface" is all
one can guarantee, so one should document it. This seems, in extremis
(and a very easily reached extreme!) to lead to documenting all
parameters regardless of whether it's easy to tell (from their name, or
the "free form" documentation for a method) what they mean. Ditto for
return values and exceptions.

However, in Emacs Lisp I never felt the need to do such things (there,
the tendency to CAPITALISE arguments makes them stand out in normal
text, and that may help). And whilst I suspect I've tended to go for the
more "formal" approach of lists of parameters, etc., in Python, I think
that's mostly a hold-over from my C, and an approach I'm less likely to
follow now, unless it makes textual sense in that particular docstring
[1]_.

I suspect that the *correct* thing to do is to require well-written
documentation, that explains what a thing does, to sufficient detail,
and police that practice in exactly the same way that the code itself is
looked after, and to exactly the same degree of seriousness. Of course,
that *is* harder to mandate in a formal document or coding standard
("write good code" as a coding standard only has the virtue of being
short...)

.. [1] An obvious example in Python would be where arguments *did*
   have particular restrictions (e.g., datatypes) on them, which
   are not obvious from other indicators. But I would assert that
   if this is so, then the failure to write the documentation like
   that would be picked up as "this is not well written".

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
Well we're safe now....thank God we're in a bowling alley.
- Big Bob (J.T. Walsh) in "Pleasantville"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)