pydoc enforcement.

[Ken Faulkner]

Hi

Yeah, I was thinking about something at commit time for a VCS...   catch is,
soo many VCS's out there.
And I wasn't thinking of the default action throwing compile errors, but
would only do that if a particular flag was given.
Still, just an idea.

I'm just finding more and more public modules/API's/libraries that have so
little documentation that it really does force reading a LOT of the source
to figure out whats going on. Sure, a lot of the time thats required, but
some modules are just painful..

oh well... was just a thought.

Ken



On Tue, Dec 2, 2008 at 3:03 AM, J. Cliff Dyer <jcd at sdf.lonestar.org> wrote:

>
> 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
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-list/attachments/20081202/62ed4fee/attachment-0001.html>