>>> def ident(x):
... return x
>>> ident
<function ident at 200c46d8>
>>> ident.__members__
['func_code', 'func_doc', 'func_globals', 'func_name']
>>> ident.func_doc
''
>>> setattr( ident, 'func_doc', 'function: ident(x) ==> x ')
>>> print getattr( ident, 'func_doc' )
function: ident(x) ==> x
I'm going to experiment/play around with the idea a bit more,
but what I'm *considering* proposing is:
(1) to make that attribute read only
(2) and rather than setting it with 'setattr', to extend the
function (and class and method) syntax with something like:
>>> def func( args ) 'optional documentation string' :
>>> class Thing( base-class ) 'optional class description' :
[ I haven't even peeked at the parser to see if this is as easy
as adding the attributes was ... I suspect not. ]
(3) I'm still thinking about the issue of short descriptions vs.
verbose documentation and whether they should use the same
sort of implementation or not.
If anything that eval's to a string is allowed in the above
syntax, then one can write:
_func_doc = 'Lines and lines ... \n' + \
'and lines and lines and ... \n' + \
'and lines of text'
def func( a,b,c ) _func_doc :
( or even "def func() function_returning_a_string( args ) :"
With the convention being that whenever there is multi-line docs,
the first line should be something that could be extracted by
itself to an 'apropos' sort of utility.
(4) Can something be automatically constructed, either as the
default, or to be prepended onto the explicit string, with
the name and arguments of the function ? - so minimally the
number of arguments expected will be shown for undocumented
functions. [ I think I can sort of guess how to do this, so
I guess the real question is: should that be the default ? ]
(5) It would be nice if builtin functions could have a doc string
compiled into them - but builtins don't have attributes, do they?
(6) Modules would use a different method: They could define their
own help function to return a string, or the default help function
would append all of the function,class and methods doc strings to
a __doc__ string defined in the module.
(7) "variables" - i.e. numbers, sequences, instances, etc. would not
have documentation strings associated with them.
(8) builtin help would check on the type of the object, and print
the appropriate attributes.
(9) help('string') or help( 'regexp-like-string' ) :
maybe that should be like apropos and print the short description
for all matches. (?)
(10) help( and-other-python-object ) would probably just print
something like 'object is a <type 'some-type'>'
Comments or suggestions ?
- Steve Majewski (804-982-0831) <sdm7g@Virginia.EDU>
- UVA Department of Molecular Physiology and Biological Physics