<span style="font-family:arial, sans-serif;font-size:13px;border-collapse:collapse"><div style="color:rgb(80, 0, 80)"><span style="background-color:rgb(255, 255, 204);color:rgb(34, 34, 34);background-repeat:initial initial">Tomeu<span style="color:rgb(80, 0, 80)">,</span></span></div> <div style="color:rgb(80, 0, 80)"><br><div><span style="color:rgb(0, 0, 0)">Thank you for the pointers.</span></div><div><span style="color:rgb(0, 0, 0)"><br></span></div></div><div>As recommended, we developed the devtutor activity, and uploaded its source code at <a href="http://git.sugarlabs.org/projects/devtutor" style="color:rgb(42, 93, 176)" target="_blank">http://git.sugarlabs.org/projects/devtutor</a>. This is an activity to help understand the Sugar APIs for the developers. </div> <div>We did get a strong insight on key areas of activity development while working on this activity.</div><div><br></div><div>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.</div> <div><br></div><div>Please have a look at the revised patch, and let us know your feedback - <a href="http://seeta.in/dextrose/API%20patch/" style="color:rgb(42, 93, 176)" target="_blank">http://seeta.in/dextrose/API%20patch/</a>.</div> <div><br></div><div>Hope it meets the requisite standards. If not, we'll be happy to revise it. </div><div><br></div><div>As discussed with you on IRC, our next step is to add documentation of modules like sugar.graphics. </div> <div><br></div><div>Regards,</div><div><br></div><div>Kandarp</div></span><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" target="_blank">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>On Sat, Aug 14, 2010 at 18:02, <<a href="mailto:sugar@dev.seeta.in" target="_blank">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> <div><div></div><div>><br> ><br> > _______________________________________________<br> > Sugar-devel mailing list<br> > <a href="mailto:Sugar-devel@lists.sugarlabs.org" target="_blank">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> </div></div></blockquote></div><br>