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

[Tomeu Vizoso]

Hi Kandarp, some comments follow inline.

On Mon, Aug 30, 2010 at 20:46, Kandarp Kaushik <kandarp at seeta.in> wrote:
> 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/.

+        """Stop animation, remove animation instance."""

Maybe "remove all animation instances" instead?

+        """Reset timeout_sid."""

timeout_sid is an implementation detail. I'm not sure we can do much
better than saying "Stops animation", maybe mentioning it will emit
the 'completed' signal if the animation was running.

+        Description: Update frame after small time gaps, end after t=duration

I would find more useful to say: "Update animation to the next frame"

+        Description: pass

This method is intended to be overridden by subclasses. We should say
so or leave it undocumented for now.

> 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.

I really think it will be a much better place to start with rather
than animator.py.

Regards,

Tomeu

> 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
>> >
>> >
>
>