pydoc enforcement.

[Marc 'BlackJack' Rintsch]

On Sun, 30 Nov 2008 16:27:07 -0800, ken.faulkner at gmail.com wrote:

> Basically I'm interested adding a check to see if:
>   1) pydoc's are written for every function/method.

Pylint warns for missing docstrings.

>   2) There are entries for each parameter, defined by some
       predetermined syntax.

But which syntax?  There are several in use out there.  Even the (I 
think) popular epydoc allows at least three, its own, something JavaDoc 
like, and ReST.

And I dislike forcing to document every parameter.  There's lots of code 
that is clear just by the names of the parameters and one or two usage 
examples in the docs.  Forcing to state the obvious again does not add 
information for the user and is annoying for the programmer.

> My idea is that as much as I love dynamic typing, there are times when
> using some modules/API's that have less than stellar documentation. I
> was thinking that if it was possible to enable some switch that
> basically forced compilation to fail if certain documentation criteria
> weren't met.

But that doesn't enforce good or even real documentation either.  Even 
worse, you can't spot the undocumented parts of the code anymore, because 
now every "docable" object has "documentation" like this just to make the 
compiler happy:

def spam(foo, bar):
    """
    :param foo: a foo object.
    :param bar: a bar object.
    """

Which basically tells the same as no documentation at all.

Ciao,
	Marc 'BlackJack' Rintsch