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.
>From these two, I have no idea what BOTH the input and return types are.
I found those examples in 10 seconds (literally). The state of the
python documentation is caca. And your complacency is a cause for
concern.
I think its easier to enforce this from the level i describe, than have
guido saying "ok guys please be more explicit in your documentation". I
mean, both of those documents above are somewhat explicit, but they are
not COMPLETE.
Could you provide me with some linkage on parsing python (from a
compilation/ syntax-tree analysis POV). SO that i can get to work on
writing a patch for the pydoc generation program.
>
>
> 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