pydoc enforcement.

[ken.faulkner]

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

 

[r]

I support any idea that supports python. You have my vote friend!

 

[Rafe]

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

 

[Marc 'BlackJack' Rintsch]

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):
"""
aram foo: a foo object.
aram bar: a bar object.
"""

Which basically tells the same as no documentation at all.

Ciao,
Marc 'BlackJack' Rintsch

 

[Richard Riley]

Pylint warns for missing docstrings.

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.


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):
"""
aram foo: a foo object.
aram 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.

 

[J. Cliff Dyer]

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

 

[J. Cliff Dyer]

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.