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