gtg-user team mailing list archive

[Lionel Dricot <ploum@xxxxxxxxx>]

Hello,

Pitijo has started a branch to convert the codebase to docstring but I
have no news from him.

And yes, it should be done, ideally ;-)



Le dimanche 12 juillet 2009 à 17:21 +1000, Jonathan Lange a écrit :
> Hello,
> 
> I've been looking around the GTG codebase a bit now, trying to see how
> things are laid out.
> 
> One thing I've noticed is that a lot of functions have comments above
> them, rather than docstrings inside them. For example:
> 
>     #Return true is the task has parent
>     #If tag is provided, return True only
>     #if the parent has this particular tag
>     def has_parents(self,tag=None):
>         #The "all tag" argument
>         if tag and len(self.parents)!=0 :
>             # ...
>         return to_return
> 
> Most of the time, you see documentation written like:
> 
>     def has_parents(self, tag=None):
>         """Does the task have parents?
> 
>         Return True if the task has parent. If 'tag' is provided, return True
>         only if the parent has this particular tag.
>         """
>         #The "all tag" argument
>         if tag and len(self.parents)!=0 :
>             # ...
>         return to_return
> 
> Is there a reason for using the "comment before function" style? Would
> you mind to much if I submit patches that change the comments into
> docstrings whenever I happen to be touching that part of the code?
> 
> See also http://www.python.org/dev/peps/pep-0257/ and
> http://www.python.org/dev/peps/pep-0008/.
> 
> jml
> 
> _______________________________________________
> Mailing list: https://launchpad.net/~gtg-user
> Post to     : gtg-user@xxxxxxxxxxxxxxxxxxx
> Unsubscribe : https://launchpad.net/~gtg-user
> More help   : https://help.launchpad.net/ListHelp