pydoc enforcement.

[Rafe]

On Dec 1, 7:27 am, "ken.faulk... at gmail.com" <ken.faulk... 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

As long as it uses RST (reStructuredText) it could be interesting.
Maybe as a wrapper on epydoc or something? I have been simply
generating my docs and reading through them. This is fine for catching
areas which are totally missing, but gets very time consuming to
maintain small changes.

What would be really great, is something which ties in to subversion
to display an easy to see and find alert in the docs when the source
has been updated. It would then require some manual action to hide the
alert (hopefully someone would read the doc again before killing the
alert).

- Rafe