[Tutor] Docstring

[Sunil Tech]

Thank you Steven D'Aprano

On Mon, Jun 8, 2015 at 4:04 PM, Steven D'Aprano <steve at pearwood.info> wrote:

> 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
> _______________________________________________
> Tutor maillist  -  Tutor at python.org
> To unsubscribe or change subscription options:
> https://mail.python.org/mailman/listinfo/tutor
>