On zaterdag, jan 4, 2003, at 22:05 Europe/Amsterdam, Brett Cannon wrote:
Question #2: How about examples(function) that displays multiple examples of how to use the function provided? Similar to above, there are times when I look at the API and even if the parameters to the function are fully explained, it would help to have an example (case in point is os.path.walk - docs are great, but an example of how to make use of the third parameter (the arg you pass) would really clarify why 'the powers that be' chose to implement this capability.
-1
If you look in the source distribution for Python there is a directory called Demos/ that has just examples of how to use things. Stuff like what you are suggesting can go there.
You can also write an examples page for the documentation.
But I don't think it belongs in the language itself.
I agree that it doesn't belong in the language itself, but what would
be nice is if the help module could point you to examples. A first stab
at this could be to use a well-defined naming scheme for the examples
(so that examples for the "os" module would be in "Demos/os", and
examples of os.walk() would be in, say, Demos/os/walk.py or walk_1.py
and walk_2.py). And this could be extended with having index files in
the Demos tree which would map Python names to example files. For
example, if there was a demo Demos/os/renamefilesintreetouppercase.py
then and index file in Demos/os could tell the help module that this is
a useful file to examine if you're interested in os.walk or os.path.
--
- Jack Jansen