Python Documentation (should be better?)

[Corrado Gioannini]

Just don't use a return statement at all, or do something like

[function body]
if not val = None:
return val
[end of function]

i didn't understood that.
if you don't return nothing explicitly the function returns None.
(or am i wrong?)

c.

 

[Tim Williams]

----- Original Message -----

Just don't use a return statement at all, or do something like

[function body]
if not val = None:
return val
[end of function]

i didn't understood that.
if you don't return nothing explicitly the function returns None.
(or am i wrong?)

No, you're right, my bad

Was thinking about something else similar and got stuck in a mindset

 

[Rocco Moretti]

*But you do have to remember that strings are documented under "sequences"
this is probably my biggest complaint about the Library Reference --- something
as important as string methods should have its own heading in the top-level
outline. But that's a nitpick, of course.

I'd agree. My one complaint about the documentation, if I had one, would
be that the organizational structure is non-intuitive. ("Why are
dictionaries/lists/strings part of the 'library'?") But once you get the
organization down, I have few complaints.

 

[John J. Lee]

At my work, we are developing a product from scratch. It is completely
modular and the modules communicate via SOAP. Because of that, we can
implement individual modules in any language of our choosing (so long as
they have good SOAP libs).

Oh dear! Have fun <wink>

[...]

After we were done, we talked about the pros and cons of the languages.
Funny, the con of Python (documentation) is PHP's strong point. The PHP
manual is extremely easy to navigate and its search feature works great.
Contrast that with Python, where you have to use "the tutorial" as the
manual. Also, the tutorial is just that...a tutorial, its a NOT a manual.
Its not organized like a manual and its not comprehensive like a manual,
hell, raw_input() isn't even mentioned in Chapter 7. Input and Output.

Did they renumber it at some point? In my copy: "7. Optional
Operating System Services".

Ohh, you mean the Language Reference? I've been working full time as
a Python programmer for over a year (and using Python for many years
before that), and I've certainly never sat down and read it start to
finish (nor even read the whole thing in pieces, over the years).

[...]

Now for the real kicker. Some of the module documentation doesn't even list
simple use cases or even the entire API. When my coworker came to me with
this complaint, my response was "oh, just load the interpreter, import the
module and call dir() on it. Then instantiate some objects and call dir()
on them also". My infatuation with Python had kept me from realizing the
sheer ridiculousness of that method to learn to use an API. Needless to
say, my coworker's reaction to that statement snapped me out of it. But
its the truth. How many of you learn a module by starting the interpreter
and "playing" around with it and using dir()?

I don't. dir(), the interactive prompt, module inspect &c. can all be
very handy at times, though.

The next complaint isn't really about documentation. Why isn't there a CPAN
or PEAR for Python? So many times I've search for a module, not found it,
started to write it myself, then later stumble across it on Google...ugh!

Fair point, but PyPI (pypi.org) is growing (and now very easy to use),
and the Vaults of Parnassus was still there last time I looked.

[...]

the future success of Python. Even I, a huge Python advocate, has started
to use PHP more often simply because I can find well documented,
semi-official modules very easily and learning PHP is a breeze with the
awesome PHP manual.

[...]

I don't recognize the problem with basic language features or module docs.

There is perhaps a problem with docs for language features on a more
advanced level than you complain about, though.


John

 

[John J. Lee]

[...]

By the way, did you try the .chm?


John