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