[Sugar-devel] Patch for documentation of graphics/animator.py

[Manusheel Gupta]

Tomeu,

Thank you for the pointers.

Appreciate it. We'll have a meeting this evening to discuss on your timely
feedback.

Regards,

Manu

On Sun, Aug 15, 2010 at 7:51 PM, Tomeu Vizoso <tomeu at sugarlabs.org> wrote:

> On Sat, Aug 14, 2010 at 18:02,  <sugar at dev.seeta.in> wrote:
> > Hello all,
> >
> > I've made some changes to the docstrings in graphics/animator.py for its
> > documentation and have uploaded the HTML generated using sphinx at:
> > http://seeta.in/sugar/api/documentation/desttemp/html2/animator.html
> >
> > You can compare it with the initial one at:
> > http://api.sugarlabs.org/sphinx/animator.html
> >
> > Attaching the original and new animator.py files along with the patch
> > generated using 'git format-patch master'
> >
> > I've also made a spreadsheet for the documentation and am maintaining it
> at
> >
> https://spreadsheets.google.com/a/seeta.in/ccc?key=0AjslliQkdNyvdFZjWnNwcEZzSC1fMkt6ZDlOOUFFMUE&hl=en#gid=0
> > Attaching it.
> >
> > Please see if you would like to help or let me know in case of any
> > suggestions/feedback.
>
> Hi Kandarp, some suggestions follow:
>
> > Subject: [PATCH] description of animator.py
>
> The docstring for the module animator.py isn't really included in this
> patch.
>
> >  animator1.py |   69
> ++++++++++++++++++++++++++++++---------------------------
>
> This is very weird as there's no animator1.py file in sugar-toolkit.
> Please go through a git tutorial first, we'll all save time.
>
> > +    :Inherits: gobject.GObject
>
> Sphinx cannot get this information from the code? Is it common
> practice in sphinx-generated docs?
>
> > +        Returns
> > +            - None
>
> Can we leave this implicit?
>
> > +        Description: Adds animation type
>
> Why type? Seems to be adding an Animation instance.
>
> > +        Parameters
> > +            - None
>
> Can we leave this implicit?
>
> > +        Description: Stops animation, removes animation type
>
> See above.
>
> > +        Description: Records starting time, sets timeout_sid
>
> Docstrings should describe functionality, not explain the implementation.
>
> > +class Animation(object):
>
> Watch out adding trailing spaces
>
> > +        Description: Updates frame, ends after t=duration
>
> PEP 257 says to use the first line for the one-line summary.
>
> Are you using any documented guidelines for the format of the docstrings?
>
> I would _strongly_ advise to start by adding docstrings to packages
> and modules. And only once that's done then get to classes and other
> top-level elements, then finally to methods.
>
> If you try to document the details before understanding the big
> picture, you are likely to fail.
>
> Regards,
>
> Tomeu
>
> > Regards,
> > Kandarp.
> >
> >
> > _______________________________________________
> > Sugar-devel mailing list
> > Sugar-devel at lists.sugarlabs.org
> > http://lists.sugarlabs.org/listinfo/sugar-devel
> >
> >
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.sugarlabs.org/archive/sugar-devel/attachments/20100815/840f5ca3/attachment.htm