This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author ezio.melotti
Recipients Arfrever, docs@python, eli.bendersky, eric.araujo, ezio.melotti, flox, leonov, scoder
Date 2012-02-23.03:36:33
SpamBayes Score 4.7515387e-05
Marked as misclassified No
Message-id <1329968193.97.0.794544535456.issue14006@psf.upfronthosting.co.za>
In-reply-to
Content
Converting sounds good to me, but it should be done carefully.

I think you can have two paragraphs in the docstrings: the first with the description of what it does and what it returns, and the second with the arguments.

For example Lib/xml/etree/ElementTree.py:355:
# Finds the first matching subelement, by tag name or path.
#
# @param path What element to look for.
# @keyparam namespaces Optional namespace prefix map.
# @return The first matching element, or None if no element was found.
# @defreturn Element or None

can become something like:
"""
Finds the first matching subelement, by tag name or path
and returns the first matching element, or None if no
 element was found.

*path* is the element to look for and *namespace* is an
optional namespace prefix map.
"""
History
Date User Action Args
2012-02-23 03:36:34ezio.melottisetrecipients: + ezio.melotti, scoder, eric.araujo, Arfrever, eli.bendersky, leonov, flox, docs@python
2012-02-23 03:36:33ezio.melottisetmessageid: <1329968193.97.0.794544535456.issue14006@psf.upfronthosting.co.za>
2012-02-23 03:36:33ezio.melottilinkissue14006 messages
2012-02-23 03:36:33ezio.melotticreate