[Tutor] Docstring

[Sunil Tech]

Hi Team,

what is the standard way of using docstrings?
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?


Thanks & Regards,
Sunil. G
_______________________________________________
Tutor maillist - ***@python.org
To unsubscribe or change subscription options:
https://mail.python.org/mailman/listinfo/tutor

[Steven D'Aprano]

Post by Sunil Tech
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.

Post by Sunil Tech
for example (Sphinx)
"""
A dummy method
x (int): first argument
"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"
"""

[Sunil Tech]

Thank you Steven D'Aprano

Post by Steven D'Aprano

Post by Sunil Tech
Hi Team,
what is the standard way of using docstrings?

There isn't one standard way of using docstrings. Different systems use
different conventions.
https://www.python.org/dev/peps/pep-0257/
http://google-styleguide.googlecode.com/svn/trunk/pyguide.html#Comments
"""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
"""
"""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
"""
"""This is Google's style.
param1 - this is the first param
param2 - this is a second param
This is a description of what is returned
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.

Post by Sunil Tech
for example (Sphinx)
"""
A dummy method
x (int): first argument
"true or false"
"""
and if the method has no arguments?
how should be the docstring?

"""A dummy method.
"true or false"
"""
--
Steve
_______________________________________________
https://mail.python.org/mailman/listinfo/tutor

_______________________________________________
Tutor maillist - ***@python.org
To unsubscribe or change subscription options:
https://mail.python.org/mailman/listinfo/tutor

[Alan Gauld]

Post by Sunil Tech
what is the standard way of using docstrings?

As Steven said there are several "standards".

Yet another option is to use the format required
by doctest. For your example:

def test(x):
"""
A dummy method

Post by Sunil Tech

test(5)

True

Post by Sunil Tech

test(-5)

False
"""

Or whatever test cases make sense.
--
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/
http://www.amazon.com/author/alan_gauld
Follow my photo-blog on Flickr at:
http://www.flickr.com/photos/alangauldphotos


_______________________________________________
Tutor maillist - ***@python.org
To unsubscribe or change subscription options:
https://mail.python.org/mailman/listinfo/tutor

[Sunil Tech]

Thanks Alan Gauld

Post by Sunil Tech
what is the standard way of using docstrings?
As Steven said there are several "standards".
Yet another option is to use the format required
"""
A dummy method

test(5)

True

test(-5)

False
"""
Or whatever test cases make sense.
--
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/
http://www.amazon.com/author/alan_gauld
http://www.flickr.com/photos/alangauldphotos
_______________________________________________
https://mail.python.org/mailman/listinfo/tutor

_______________________________________________
Tutor maillist - ***@python.org
To unsubscribe or change subscription options:
https://mail.python.org/mailman/listinfo/tutor