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 <[EMAIL PROTECTED]> > wrote: > > > On Sun, 2008-11-30 at 16:27 -0800, [EMAIL PROTECTED] > 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 > > > > > -- http://mail.python.org/mailman/listinfo/python-list