[Tutor] Docstring

[Steven D'Aprano]

On Mon, Jun 08, 2015 at 03:04:05PM +0530, Sunil Tech wrote:
> Hi Team,
> 
> what is the standard way of using docstrings?

There isn't one standard way of using docstrings. Different systems use 
different conventions.

The conventions for the Python standard library are described here:

https://www.python.org/dev/peps/pep-0257/

The conventions used by Google are here:

http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments


Epydoc uses Javadoc conventions:

   """This is a javadoc style.

   @param param1: this is a first param
   @param param2: this is a second param
   @return: this is a description of what is returned
   @raise keyError: raises an exception
   """


Sphinx uses ReST conventions:

   """This is a ReST style.

   :param param1: this is a first param
   :param param2: this is a second param
   :returns: this is a description of what is returned
   :raises keyError: raises an exception
   """

and also understands Google's conventions:

    """This is Google's style.

    Parameters:
        param1 - this is the first param
        param2 - this is a second param

    Returns:
        This is a description of what is returned

    Raises:
        KeyError - raises an exception
    """


Numpy also has their own custom format, which apparently 
Sphinx also understands. Pycco uses Markdown rather than ReST. There's 
also Doxygen, but I don't know what it uses. So that's *at least* five 
different conventions.



> for example (Sphinx)
> def test(x):
>     """
>     A dummy method
>     Args:
>         x (int): first argument
>     Returns:
>         "true or false"
>     """
> 
> and if the method has no arguments?
> how should be the docstring?


Just leave it out:


    """A dummy method.

    Returns:
        "true or false"
    """



-- 
Steve