Nice work...
> but what I'm *considering* proposing is:
>
> (1) to make that attribute read only
Yes
> (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. ]
This should be easy enough to add to the parser. It's quite an
original placement of the documentation string. However I'm not sure
that it meets the criterion for easy readability -- if most Python
code had a very long documentation string at each class and function,
most colons would end up at rather weird places (especially since in
most cases the documentation string would be many lines long).
My own suggestion would be along these lines:
def gcd(a, b):
__doc__ = '\
Compute Greatest Common Diviso of a and b.
Works even for long integers.
'
while b:
a, b = b, a%b
return a
This needs a hack in the compiler but I feel it looks slightly better
and is more extensible. It also needs a change to the tokenizer to
accept multiline string literals but I'm slowly getting convinced that
that's necessary anyway. Of course there's the issue of what the
indentation would mean -- for multiline literals in general and/or for
documentation strings...
> (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.
Could perhaps be solved with __help__ vs. __doc__? I would like to
see the long doc string use some formatting language. Currently I
feel that texinfo would have the right level -- it's easily converted
to various other formats (e.g. HTML as used by the world-wide web for
viewing using e.g. Mosaic, or Emacs info for viewing on ASCII
terminals) and supports sufficiently rich formatting. Also it's
semi-decent to view with the mark-up left in, unlike HTML (which is a
bit verbose), and it doesn't use backslashes like LaTeX or Microsoft
RTF (which would interfere with string literal parsing).
> 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 ) :"
In my proposal this could also work, as long as the expression
wouldn't use arguments.
> 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.
That's another way, though I can imagine that it would be better if it
were explicit.
> (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 ? ]
I think I could hack the parser to automatically add an attribute to
each function object describing the arguments, so that gcd.func_args
would return ('a', 'b'). If this was always there, the help and doc
strings could assume it and refer to the arguments by name without
introducing them first.
> (5) It would be nice if builtin functions could have a doc string
> compiled into them - but builtins don't have attributes, do they?
They don't, currently, but it could always be added. In fact it may
be combined (after a serious redesign of some internals :-) with the
actual argument parsing of built-in functions. Someone once sent me
a vastly improved getargs() that might prove useful here...
> (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.
That would perhaps a bit long -- perhaps a list of functions and
classes would be more appropriate?
> (7) "variables" - i.e. numbers, sequences, instances, etc. would not
> have documentation strings associated with them.
I can imagine that sometimes one would like to document them; but
maybe this can just go in the module doc.
> (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. (?)
"All" is hard to define -- over all possible modules? All modules
that have already been imported? I would personally be happy with
different functions for getting help on an object and apropos-like
functions.
> (10) help( and-other-python-object ) would probably just print
> something like 'object is a <type 'some-type'>'
--Guido van Rossum, CWI, Amsterdam <Guido.van.Rossum@cwi.nl>