On Wed, 2002-09-04 at 19:19, Raymond Hettinger wrote:
From: "Hunter Peress" hu.peress@mail.mcgill.ca
def something(a,b,c="lalal"): """This will find its way into the pydocs because its a comment""" ##Here is the new stuff Im proposing ##note, a clearer sytnax can surely be devised. """file""" #documents the type of the first arg """string""" # "" second """list""" # "" third """string""" #documents the return type.
Then the pydoc generator will do a check on the # arguments to the func/meth, verify that the correct amount of these new comments (which only supply the type) are provided. I do think that it would help to actually enforce this. I think its fine that doc's NOT be generated if they don't supply this information. This provides for better docs and shouldnt get that many complaints.
Thanks for the clarification. I see what you're trying to do; however, I think that any gains are more than offset by the new level of complexity and lengthier code.
The current docs make a pretty good effort at describing what is needed for each argument. At the same time, they allow flexibility for dynamic arguments that share a similar interface (such as substituting a StringIO object for a File object.
In your example, the docs strings could be made clear using existing tools:
def something(file, promptstring, optionlist): """Returns a string extracted from the file for any line matching the promptstring. The optionlist can include any of the following: IGNORECASE, VERBOSE. MULTILINE, or ADDLINENUMBER."""
I can't see that a tool like you described would add any more clarity than the above docstring.
PS whats TIA mean?
"Thanks In Advance"
Do you have any examples of current python docstrings that are not clear enough?
this was the impetus behind my whole thinking here.
I need not search far. example 1) pydoc os.fork Python Library Documentation: built-in function fork in os fork(...) fork() -> pid Fork a child process.
Return 0 to child process and PID of child to parent process.
example2) pydoc string.index Python Library Documentation: function index in string index(s, *args) index(s, sub [,start [,end]]) -> int
Like find but raises ValueError when the substring is not found.