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

Ok. I think I understand better what you're trying to accomplish. I got the impression earlier (and I think others did as well) that you were hoping to have pydoc automatically label types on the function call. A new convention might very well be welcomed. You might want to post a couple of examples and the corresponding documentation for feedback here before you start the hard work on the patch :)

More below...

On Sun, Sep 08 @ 02:11, Hunter Peress wrote:

Actually all of the thinking i did WAS taking into account the "dynamic" nature of python.

But its not like the actual code is being rewritten fast enough to make this unfeasible or unneccesary.

Im glad to get all of this feedback as its helping me formulate, and further specify my plans (or eventually healthily debunk them (as the past 3 responders have helped do)).

Instead of just thinking:

"arguments are not explicitely anything, therefore it makes no sense to even attempt to document them explicitely".

I think this: simply add the capability for multiple definitions per each argument. eg going back to my original sample here is an updated version:

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,socket""" #documents the type(s) of the first arg """string,list""" # "" second """list,hash""" # "" third """string,hash""" #documents the return type(s).

Thats quite a simple solution, and still provides worlds better exactness and clarity than the current system allows.

Onto more of your concerns: On Wed, 2002-09-04 at 23:45, Michael Gilfix wrote:

...

While I understand what you're trying to do here (and think it would be quite nice), I'm not sure how you're going to accomplish it. How will parsing python using a syntax-tree help? It's not going to tell you what the function does in all cases or the various types it could handle.Perhaps you could make educated guesses by looking at the types of operations on the objects (a 'has_key' is a sure indicator of a hash), but that would be sketchy at best.

Actually I wasnt suggesting this AT ALL wrt intelligent guesses, and for now this proposal leans away from it.

Rather there are only 2 simple things that I wanted to obtain from the parse-tree: the number of arguments, and if possible to see if there

Agreed now that things are clearer.

Assume for now that my whole proposal will simply be another option (instead of the default) to the pydoc-generator program. If invoked, it will fail (if the super strict option is specified) if you don't supply definitions for number of args for a given method.

This brings up your "dynamic" language issue again.

When u have lots of args being used as different things, my program then introduces another level of complexity to deciphering the docs in a meaningful way.

Eg: a sample output of this program based on my example:

------------output----------------- method: something(a (file,socket),b (string,list),c="lalal" (list,hash)) return type :string,hash

This will find its way into the pydocs because its a comment

Now in html format it would be even nicer as there will be links to the types listed.

I agree. I know that I'd welcome an extra added option to enable some extra pydoc functionality. Developing a schema is tricky though and you should probably engage in some more debate first :)

And now looking at it, I think its much clearer than nothing at al.

Of course there is going to be that type of code where u have no need of documenting every method because their names are self explantory, and such explicit documentation isnt necessary, thats not what this is really intended for.

If the specific argument arises that "since python is a dynamic language your approach doesnt make sense" say, then I have to respond:

Of course it applies. Because of my misunderstanding, I was under the impression that you wanted to generate the equivalent of function calls, not develop a scheme like javadoc. The dynamic nature of Python means that such specifications become even more important as project sizes increase.

an attempt at specifiying things is FAR better than nothing, and moreover, this is only my first attempt. Allowing it to become a part of the generator as an option will open it up to user input, and hence improvement, AND!

---

it might just turn out that a "dynamic" approach will be necessary to document a "dynamic" language.

---

So im still looking for more design tips, and a place where I could find out how to get into the meat of the python parser, but i think the "http://python.org/doc/2.2/lib/module-parser.html" is probably what I'll be using.

Shouldn't there be code in the existing pydoc to do much of what you want for you? It seems like it might be nice to re-engineer pydoc to take some handlers that allow you to do further customization after it's done it's thing. That way, we can add extensions into the existing code and all that integration stuff might be a little easier.

Good luck n' keep us posted :)

-- Mike

my only objection is that the case where fork fails isn't documented. with a C background one expects a negative number, when in fact an exception is raised...

Ah jeez. Even with only half a day of Python you should've figured out that Python nearly always raises an exception where the corresponding C code returns an error value.

--Guido van Rossum (home page: http://www.python.org/~guido/)

guido wrote:

...

my only objection is that the case where fork fails isn't documented. with a C background one expects a negative number, when in fact an exception is raised...

Ah jeez. Even with only half a day of Python you should've figured out that Python nearly always raises an exception where the corresponding C code returns an error value.

otoh, it doesn't hurt to spell it out for functions like fork which almost always succeeds...

(can you write a portable test that is guaranteed to raise an exception, and does that without locking up the system?)

</F>

It would, however, be extremely useful if the documentation spelled out *which* exceptions can be raised! Kind of hard to write a decent try/except clause if you don't know what to expect.

Yes, *this* is a deficiency in the Python docs that ought to be fixed. It's a lot of work though, and it's not always clear what to document (e.g. *everything* can raise MemoryError -- so it's not useful to mention that everywhere).

--Guido van Rossum (home page: http://www.python.org/~guido/)

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.

for i in a: print os.spawnv(os.P_NOWAIT,scr,["",str(i)])

for i in a: os.wait()

you have to do the second loop in order to wait for all children that u spawned off. I think that os.wait() without any arguments should wait for all chilren, not wait for the earliest executed child.

On Thu, 2002-09-05 at 17:06, Fredrik Lundh wrote:

hunter wrote:

...

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.

why do you care about the type of a PID object? in most cases, all you need to know is that a PID isn't 0, which is exactly what the documentation says.

and if you know what a PID is, you already know what type it is...

...

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.

the index documentation refers to the documentation for "find", which tells you that:

...

...

...

help(string.find)

Help on function find in module string:

find(s, *args) find(s, sub [,start [,end]]) -> in

Return the lowest index in s where substring sub is found,
such that sub is contained within s[start,end].  Optional
arguments start and end are interpreted as in slice notation.

Return -1 on failure.

which, given that you know how indexes and slices work in python, is all you need to know.

...

I found those examples in 10 seconds (literally). The state of the python documentation is caca.

how long have you been using Python?

</F>

The idea came from bash. where the wait command will wait for all child processes.

Its clearly doable. On Mon, 2002-09-23 at 10:42, Guido van Rossum wrote:

...

for i in a: print os.spawnv(os.P_NOWAIT,scr,["",str(i)])

for i in a: os.wait()

you have to do the second loop in order to wait for all children that u spawned off. I think that os.wait() without any arguments should wait for all chilren, not wait for the earliest executed child.

Go talk to the designers of Unix and the POSIX standard committee.

--Guido van Rossum (home page: http://www.python.org/~guido/)