Hi<br><br>Yeah, I was thinking about something at commit time for a VCS...   catch is, soo many VCS's out there. <br>And I wasn't thinking of the default action throwing compile errors, but would only do that if a particular flag was given.<br>
Still, just an idea.<br><br>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..<br>
<br>oh well... was just a thought.<br><br>Ken<br><br><br><br><div class="gmail_quote">On Tue, Dec 2, 2008 at 3:03 AM, J. Cliff Dyer <span dir="ltr"><<a href="mailto:jcd@sdf.lonestar.org">jcd@sdf.lonestar.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;"><div><div></div><div class="Wj3C7c"><br>
On Sun, 2008-11-30 at 16:27 -0800, <a href="mailto:ken.faulkner@gmail.com">ken.faulkner@gmail.com</a> wrote:<br>
> I've been thinking about implementing (although no idea yet *HOW*) the<br>
> following features/extension for the python compile stage and would be<br>
> interested in any thoughts/comments/flames etc.<br>
><br>
> Basically I'm interested adding a check to see if:<br>
>   1) pydoc's are written for every function/method.<br>
>   2) There are entries for each parameter, defined by some<br>
> predetermined syntax.<br>
><br>
> My idea is that as much as I love dynamic typing, there are times when<br>
> using some modules/API's that have less than stellar documentation. I<br>
> was thinking that if it was possible to enable some switch that<br>
> basically forced compilation to fail if certain documentation criteria<br>
> weren't met.<br>
><br>
> Yes, it should be up to developers to provide documentation in the<br>
> first place. Or, the client developer might need to read the source<br>
> (IF its available)...  but having some "forced" documentation might at<br>
> least ease the problem a little.<br>
><br>
> For example (half borrowing from Javadoc).<br>
><br>
> class Foo( object ):<br>
><br>
>   def bar( self, ui ):<br>
>      pass<br>
><br>
><br>
> Would fail, since the bar method has an "unknown" parameter called<br>
> "ui".<br>
> What I think could be interesting is that the compiler forces some<br>
> documentation such as:<br>
><br>
> class Foo( object ):<br>
><br>
>   def bar( self, ui ):<br>
>     """<br>
>     @Param: ui :  blah blah blah.<br>
>     """<br>
>      pass<br>
><br>
><br>
> The compiler could check for @Param matching each parameter passed to<br>
> the method/function. Sure, a lot of people might just not put a<br>
> description in, so we'd be no better off. But at least its getting<br>
> them *that* far, maybe it would encourage them to actually fill in<br>
> details.<br>
><br>
> Now ofcourse, in statically  typed language, they might have the<br>
> description as "Instance of UIClass" or something like that. For<br>
> Python, maybe just a description of "Instance of abstract class UI" or<br>
> "List of Dictionaries"...  or whatever. Sure, precise class names<br>
> mightn't be mentioned (since we mightn't know what is being used<br>
> then), but having *some* description would certainly be helpful (I<br>
> feel).<br>
><br>
> Even if no-one else is interested in this feature, I think it could<br>
> help my own development (and would be an interested "first change"<br>
> into Python itself).<br>
><br>
> Apart from bagging the idea, does anyone have a suggestion on where in<br>
> the Python source I would start for implementing such an idea?<br>
><br>
> Thanks<br>
><br>
> Ken<br>
<br>
</div></div>For the reasons already stated, I think it's probably a bad idea to<br>
enforce this at compile time.  I think it's a great idea to make sure<br>
that this information is present in all your code, but unless you want<br>
to see useless stubs, the correct time to enforce this is at commit<br>
time.  Don't accept any improperly documented patches.<br>
<br>
Syntax is not enough to ensure what you want to ensure.  The semantics<br>
have to be right as well.<br>
<br>
Cheers,<br>
<font color="#888888">Cliff<br>
<br>
<br>
<br>
<br>
</font></blockquote></div><br>