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 <to...@sugarlabs.org> wrote: > On Sat, Aug 14, 2010 at 18:02, <su...@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@lists.sugarlabs.org > > http://lists.sugarlabs.org/listinfo/sugar-devel > > > > >
_______________________________________________ Sugar-devel mailing list Sugar-devel@lists.sugarlabs.org http://lists.sugarlabs.org/listinfo/sugar-devel