Thank you Steven D'Aprano On Mon, Jun 8, 2015 at 4:04 PM, Steven D'Aprano <st...@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@python.org > To unsubscribe or change subscription options: > https://mail.python.org/mailman/listinfo/tutor > _______________________________________________ Tutor maillist - Tutor@python.org To unsubscribe or change subscription options: https://mail.python.org/mailman/listinfo/tutor
