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?
Raymond Hettinger
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4