pydoc enforcement.

[Filip Gruszczyński]

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 ken.faulkner at gmail.com <ken.faulkner at gmail.com>:
> 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