Add docstring

[MarcCote]

Make sure we provide useful docstring.

[ASalvail]

We need to find a format asap. Some suggestions : http://stackoverflow.com/a/24385103

[mgermain]

De ton link "Note that the reST is recommended by the PEP 287 https://www.python.org/dev/peps/pep-0287"

Donc worst case on fallback sur cella, mais j'aime bien cella de google je le trouve pas mal plus claire. Un ou l'autre me derange pas.

On Tue, Jul 14, 2015 at 4:43 PM, ASalvail notifications@github.com wrote:

We need to find a format asap. Some suggestions : http://stackoverflow.com/a/24385103

— Reply to this email directly or view it on GitHub https://github.com/SMART-Lab/smartpy/issues/11#issuecomment-121378850.

[MarcCote]

Because Python is dynamically typed, APIs can be somewhat confusing without clear docstrings. Personally, I found Numpydoc much clearer since it provides information about what a given function expects in inputs (it is also usable by Sphinx as the others).

That being said, we should use a format that is supported by readthedocs.org. An online documentation is infinitely better than the best offline format.

[mgermain]

I don't see the advantage of numpy over google. The main diff is that numpy takes more space. On Jul 15, 2015 15:49, "Marc-Alexandre Côté" notifications@github.com wrote:

Because Python is dynamically typed, APIs can be somewhat confusing without clear docstrings. Personally, I found Numpydoc much clearer since it provides information about what a given function expects in inputs (it is also usable by Sphinx as the others).

That being said, we should use a format that is supported by readthedocs.org https://read-the-docs.readthedocs.org/en/latest/getting_started.html. An online documentation is infinitely better than the best offline format.

— Reply to this email directly or view it on GitHub https://github.com/SMART-Lab/smartpy/issues/11#issuecomment-121622278.

[MarcCote]

In the google format the type of the parameter will have to be specified as text in the description of the parameter anyway. The information is still there but might be less easy to see it at first glance. I also don't think space is an issue if it helps to be clearer.

[ASalvail]

Personally, I'm used to the numpy format. It is long (quite long actually) and not supported for automatic docstring generation (that I know of).

Two criterion I'd look at : I want sphinx to work with it (giving us the online doc), but especially, I want the docstrings to be mostly generated automatically. Otherwise, we'll simple put off writing doc until it's too late.

[ASalvail]

Nevermind : https://github.com/dadadel/pyment generates numpydocs. That'd be my first choice. Anyone against?

[MarcCote]

"Pyment will generate docstrings where it doesn't exist. It will complete where it is partial. Or it will simply convert where the format is not the wanted one."

So, basically we can write the docstring in the format we want and pyment will convert it to reST. :D

[ASalvail]

Interesting thing to add : https://www.python.org/dev/peps/pep-0484/ https://www.jetbrains.com/pycharm/help/type-hinting-in-pycharm.html

Unless decided otherwise, I'll add these type hints to functions (if only for docstring autogen).

[MarcCote]

@ASalvail have you check that it does help pyment generate docstring including parameters type? Do you know, if it is compatible with numpy style docstring? Obviously pep-0484 only shows examples using reST (PEP 287).

[MarcCote]

Also, is it supported by python 3.3 or only python 3.5?

[ASalvail]

The annotations, yes. The specific annotations that'll become standard in 3.5, no. You can still put them in, it won't make any error, but it'll be supported for use by introspection tools.

[ASalvail]

It does help in pycharm; I don't know about the doc generator.