pydoc enforcement.

[ken.faulkner at gmail.com]

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