Re: pydoc enforcement.
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 > > > >
Re: pydoc enforcement.
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
Re: pydoc enforcement.
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
Re: pydoc enforcement.
Marc 'BlackJack' Rintsch <[EMAIL PROTECTED]> writes: > On Sun, 30 Nov 2008 16:27:07 -0800, [EMAIL PROTECTED] wrote: > >> Basically I'm interested adding a check to see if: >> 1) pydoc's are written for every function/method. > > Pylint warns for missing docstrings. > >> 2) There are entries for each parameter, defined by some >predetermined syntax. > > But which syntax? There are several in use out there. Even the (I > think) popular epydoc allows at least three, its own, something JavaDoc > like, and ReST. > > And I dislike forcing to document every parameter. There's lots of code > that is clear just by the names of the parameters and one or two usage > examples in the docs. Forcing to state the obvious again does not add > information for the user and is annoying for the programmer. > >> 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. > > But that doesn't enforce good or even real documentation either. Even > worse, you can't spot the undocumented parts of the code anymore, because > now every "docable" object has "documentation" like this just to make the > compiler happy: > > def spam(foo, bar): > """ > :param foo: a foo object. > :param bar: a bar object. > """ > > Which basically tells the same as no documentation at all. > > Ciao, > Marc 'BlackJack' Rintsch +1. Agreed 100%. There is nothing worse than auto generate "useless" documentation or over commenting of "obvious" variables/members. If anything it leads to problems later during maintenance. -- important and urgent problems of the technology of today are no longer the satisfactions of the primary needs or of archetypal wishes, but the reparation of the evils and damages by the technology of yesterday. ~Dennis Gabor, Innovations: Scientific, Technological and Social, 1970 -- http://mail.python.org/mailman/listinfo/python-list
Re: pydoc enforcement.
On Sun, 30 Nov 2008 16:27:07 -0800, [EMAIL PROTECTED] wrote: > Basically I'm interested adding a check to see if: > 1) pydoc's are written for every function/method. Pylint warns for missing docstrings. > 2) There are entries for each parameter, defined by some predetermined syntax. But which syntax? There are several in use out there. Even the (I think) popular epydoc allows at least three, its own, something JavaDoc like, and ReST. And I dislike forcing to document every parameter. There's lots of code that is clear just by the names of the parameters and one or two usage examples in the docs. Forcing to state the obvious again does not add information for the user and is annoying for the programmer. > 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. But that doesn't enforce good or even real documentation either. Even worse, you can't spot the undocumented parts of the code anymore, because now every "docable" object has "documentation" like this just to make the compiler happy: def spam(foo, bar): """ :param foo: a foo object. :param bar: a bar object. """ Which basically tells the same as no documentation at all. Ciao, Marc 'BlackJack' Rintsch -- http://mail.python.org/mailman/listinfo/python-list
Re: pydoc enforcement.
On Dec 1, 7:27 am, "[EMAIL PROTECTED]" <[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 As long as it uses RST (reStructuredText) it could be interesting. Maybe as a wrapper on epydoc or something? I have been simply generating my docs and reading through them. This is fine for catching areas which are totally missing, but gets very time consuming to maintain small changes. What would be really great, is something which ties in to subversion to display an easy to see and find alert in the docs when the source has been updated. It would then require some manual action to hide the alert (hopefully someone would read the doc again before killing the alert). - Rafe -- http://mail.python.org/mailman/listinfo/python-list
Re: pydoc enforcement.
I support any idea that supports python. You have my vote friend! -- http://mail.python.org/mailman/listinfo/python-list
Re: pydoc enforcement.
Hey! If you are interested, I have written a small tool for declaring variables and attributes. It's not very sophisticated, because I have written it solely for own use. It might be useful though. You can download it from you: http://code.google.com/p/pyver/downloads/list For a small example, it works like this: def foo(): a = 5 class Bar: def __init__(self): self.a = 5 Errors: Line 2: Variable a in function foo was not specified; Line 7: Field a in function __init__ was not specified; To have it working fine, you have to declare fields and variables like this: def foo(): #| a | a = 5 class Bar: #| a | def __init__(self): self.a = 5 But as soon as I finished I realized, I don't really need this since there are pychecker and pylint that do all what I need and I don't have to type all those declarations. But I have learned how to parse python code using tools from stdlib, so it wasn't really wasted time. Hope this helps :-) If you want to know something more about this, don't hesitate to ask. 2008/12/1 [EMAIL PROTECTED] <[EMAIL PROTECTED]>: > 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 > > -- > http://mail.python.org/mailman/listinfo/python-list > -- Filip Gruszczyński -- http://mail.python.org/mailman/listinfo/python-list
pydoc enforcement.
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 -- http://mail.python.org/mailman/listinfo/python-list
