Long ago, I hacked Objects/funcobject.c to add a func_doc attribute
and make it RW-able. ( The other function attribs are RO ), and I
proposed extending the function & method definition syntax to:
def func( args... ) "an optional documentation string before the colon" :
But that didn't get any wild support.
Then I experimented with a convention that comments immediately
following a def line were documentation comments.
The following ( and the code at the end of this message ) should
work even without the hacked code - describe checks if
hasattr( function, "func_doc" ). [ The test code didn't, so I
stripped some of it out. ]
>>> import describe
>>> print describe.describe( describe.describe )
def describe( func ):
# [ PROTOTYPE help function ]
# return the functions documentation string.
# if func.func_doc attributes exists and is not empty,
# that is returned. Else, the functions 'def' line
# and the immediately following comment lines are
# returned, and as a side effect, func_doc is set.
Recently, my focus has shifted to trying to integrate a python-help
function with Mosaic or some other browser, and figuring out how
to integrate Literate Programming methods to use WWW tools as a
class browser for Python, and to support distributed collaboration
and code reuse. ( Instead of asking Guido to become administrator
of Python/lib/contrib, why not distribute the maintainence job ? )
The thought of adding "import URL://host/Python/Lib/module" to
the language is what got me on the safety thread.
[ There is also some recent discussion of this in the archives. ]
- Steve Majewski (804-982-0831) <sdm7g@Virginia.EDU>
- UVA Department of Molecular Physiology and Biological Physics
--------
#!/usr/local/bin/python
# describe.py
# online help
from linecache import getline
from dis import SET_LINENO
import sys
MAXLINES=128
def describe( func ):
# [ PROTOTYPE help function ]
# return the functions documentation string.
# if func.func_doc attributes exists and is not empty,
# that is returned. Else, the functions 'def' line
# and the immediately following comment lines are
# returned, and as a side effect, func_doc is set.
if hasattr( func, 'func_doc' ) :
doc = getattr( func, 'func_doc' )
if doc : return doc
name = func.func_code.co_name
file = func.func_code.co_filename
code = func.func_code.co_code
if ( ord(code[0]) == SET_LINENO ):
lineno = ord(code[1]) + ( ord(code[2]) << 8 )
else: return None
doc = getline( file, lineno )
for lineno in range( lineno+1, lineno+MAXLINES ):
line = getline( file, lineno )
if line[0] == '#' : doc = doc + line
else: break
if hasattr( func, 'func_doc' ):
setattr( func, 'func_doc', doc )
return doc
if __name__ == '__main__' :
print 'describe( describe ) ==> '
print describe( describe )