Ezio Melotti <ezio.melotti@gmail.com> 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 <report@bugs.python.org> <http://bugs.python.org/issue14006> _______________________________________