pydoc enforcement.

[J. Cliff Dyer]

On Sun, 2008-11-30 at 16:27 -0800, ken.faulkner at gmail.com wrote:
> I've been thinking about implementing (although no idea yet *HOW*) the
> following features/extension for the python compile stage and would be
> interested in any thoughts/comments/flames etc.
> 
> Basically I'm interested adding a check to see if:
>   1) pydoc's are written for every function/method.
>   2) There are entries for each parameter, defined by some
> predetermined syntax.
> 
> 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.
> 
> Yes, it should be up to developers to provide documentation in the
> first place. Or, the client developer might need to read the source
> (IF its available)...  but having some "forced" documentation might at
> least ease the problem a little.
> 
> For example (half borrowing from Javadoc).
> 
> class Foo( object ):
> 
>   def bar( self, ui ):
>      pass
> 
> 
> Would fail, since the bar method has an "unknown" parameter called
> "ui".
> What I think could be interesting is that the compiler forces some
> documentation such as:
> 
> class Foo( object ):
> 
>   def bar( self, ui ):
>     """
>     @Param: ui :  blah blah blah.
>     """
>      pass
> 
> 
> The compiler could check for @Param matching each parameter passed to
> the method/function. Sure, a lot of people might just not put a
> description in, so we'd be no better off. But at least its getting
> them *that* far, maybe it would encourage them to actually fill in
> details.
> 
> Now ofcourse, in statically  typed language, they might have the
> description as "Instance of UIClass" or something like that. For
> Python, maybe just a description of "Instance of abstract class UI" or
> "List of Dictionaries"...  or whatever. Sure, precise class names
> mightn't be mentioned (since we mightn't know what is being used
> then), but having *some* description would certainly be helpful (I
> feel).
> 
> Even if no-one else is interested in this feature, I think it could
> help my own development (and would be an interested "first change"
> into Python itself).
> 
> Apart from bagging the idea, does anyone have a suggestion on where in
> the Python source I would start for implementing such an idea?
> 
> Thanks
> 
> Ken

For the reasons already stated, I think it's probably a bad idea to
enforce this at compile time.  I think it's a great idea to make sure
that this information is present in all your code, but unless you want
to see useless stubs, the correct time to enforce this is at commit
time.  Don't accept any improperly documented patches.  

Syntax is not enough to ensure what you want to ensure.  The semantics
have to be right as well.

Cheers,
Cliff