pydoc enforcement.

[J. Cliff Dyer]

On Tue, 2008-12-02 at 09:38 +1100, Ken Faulkner wrote:
> 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 meant more that a cultural solution might work better than a technical
one.  Don't allow commits that aren't documented, and *properly*
documented.  If you find them, back them out, scold the commiter, and
revise.


> 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
>         
>         
>         
>         
>