[Python-Dev] Call for clarity ( clarification ;-) )

Hunter Peress hu.peress@mail.mcgill.ca
07 Sep 2002 21:22:40 -0500


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
> 
>