Ezio Melotti added the comment:
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.
"""
----------
_______________________________________
Python tracker
http://bugs.python.org/issue14006
_______________________________________