pydoc enforcement.

[Richard Riley]

Marc 'BlackJack' Rintsch <bj_666 at gmx.net> writes:

> 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

+1. Agreed 100%. There is nothing worse than auto generate "useless"
documentation or over commenting of "obvious" variables/members. If
anything it leads to problems later during maintenance.

-- 
 important and urgent problems of the technology of today are no longer the satisfactions of the primary needs or of archetypal wishes, but the reparation of the evils and damages by the technology of yesterday.  ~Dennis Gabor, Innovations:  Scientific, Technological and Social, 1970