Python built-in 'example()' facility [was improving the Python docs ...]

Gyro Funch gyromagnetic at excite.com
Wed May 5 14:23:57 EDT 2004


<snip>
> He did read the documentation for lstrip, but the doc doesn't make it at all
> clear that the argument to lstrip is treated as a set of characters.
> 
> With the PHP documentation model, there would have been a user comment and
> example attached to the lstrip doc explaining this.
> 
> Asking for patches and comments via Sourceforge is nowhere near as effective
> as having a comment box right on the doc page. Someone has to be really
> motivated to take the trouble to go to SF to submit a comment. A comment box
> makes it easy.
> 
> -Mike
> 

Hi,
Would it make sense to work toward a built-in function 'example()' 
analogous to Python's built-in help facility?

 >>> help(str.lstrip) 

Help on method_descriptor:

lstrip(...)
     S.lstrip([chars]) -> string or unicode

     Return a copy of the string S with leading whitespace removed.
     If chars is given and not None, remove characters in chars 
instead.
     If chars is unicode, S will be converted to unicode before 
stripping


 >>> example(str.lstrip)
Example of usage:
     >>> 'xxxmy test'.lstrip('x')
     'my test'


Perhaps the 'example' facility could present one or more examples 
of typical usage and illustrate any relevant 'gotchas'.

-g



More information about the Python-list mailing list