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

[Fredrik Lundh]

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>