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

[Kandarp Kaushik]

Tomeu,

Thank you for the pointers.

As recommended, we developed the devtutor activity, and uploaded its source
code at http://git.sugarlabs.org/projects/devtutor. This is an activity to
help understand the Sugar APIs for the developers.
We did get a strong insight on key areas of activity development while
working on this activity.

We also revised the patch based on your feedback and recommendations. Thank
you for your time. We are using PEP 257 as the documentation standard.

Please have a look at the revised patch, and let us know your feedback -
http://seeta.in/dextrose/API%20patch/.

Hope it meets the requisite standards. If not, we'll be happy to revise it.

As discussed with you on IRC, our next step is to add documentation of
modules like sugar.graphics.

Regards,

Kandarp

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/20100831/3e81c9f1/attachment-0001.htm