Finding documentation (WAS: Iteration over strings)

[steve at holdenweb.com (Steve Holden)]

Jay Loden wrote:
> Steve Holden wrote:
>> In this particular case the documentation is quite explicit about the 
>> return value and the documentation for the function runs to almost 400 
>> words. Do you expect *everything* to be in the source? That isn't 
>> practical, as documenting everything twice like that makes twice the 
>> work when the function changes and the documentation has to be rewritten.
> 
> (starting a new thread so that we're not off topic for the original one)
> 
Well, you *think* you have started a new thread, but in fact you have 
just changed the title of the existing one :-)

> Hmmm. Jerry Hill pointed out also that this information is documented clearly in the online docs (as opposed to docstrings I was looking at with pydoc). I guess I'm just confused about the purpose of pydoc and module documentation. I was under the impression it was intended to serve as the API reference, so when people say "consult the documentation" I usually check pydoc first before hitting the web browser. I was under the impression earlier that docs.python.org was mostly generated from the docstrings similar to how javadocs are converted to html.
> 
> That being said, it does make sense to me however that you should be able to use pydoc to tell you simple things like the return value of a function, the required parameters, etc. I'd be interested to hear from some more experienced programmers what your typical usage would be when reference documentation for a given module. 
> 
> Are the HTML docs (e.g. what's on http://docs.python.org/) the canonical source? Is that where I should generally be looking? Are there other documentation resources you all have found useful as well? I'm curious to see if there are useful resources I'm just missing due to lack of knowledge or experience. 
> 
When people say "read the documentation" they generally mean the docs as 
distributed with each release, and docs.python.org is the easiest way to 
find the docs for the current release.

There are several groups whose plans for documentation world dominance 
would somehow merge the documentation and the source. Personally I think 
the documentation in the source should be just enough to remind you how 
to use something you have already used before, so not understanding them 
is a good clue you need to look at docs.python.org.

regards
  Steve
-- 
Steve Holden        +1 571 484 6266   +1 800 494 3119
Holden Web LLC/Ltd           http://www.holdenweb.com
Skype: holdenweb      http://del.icio.us/steve.holden
--------------- Asciimercial ------------------
Get on the web: Blog, lens and tag the Internet
Many services currently offer free registration
----------- Thank You for Reading -------------