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

[Raymond Hettinger]

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