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

[Tomeu Vizoso]

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