On Sun, 30 Nov 2008 16:27:07 -0800, [EMAIL PROTECTED] 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 -- http://mail.python.org/mailman/listinfo/python-list