It's actually inspired by Common Lisp, where defun,lambda,defvar,etc.
all have a optional doc-string. In defun & lambda, it's after
the argument list and before the body of the function. ( also where
optional declarations go. )
Anyone know what emacs lisp does ? It has an 'apropos' and a 'describe'
so I assume there is a similar feature, if not the same syntax.
> 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).
>
I think it's quite readable _when_ it's short.
>
> > (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.
So it makes sense to have a short string and a longer function/string/
whatever. The short string should have a default value automatically
constructed. The long documentation would have no default. And maybe
it would be a more complex object than a string - it might have an
attribute that says how it should be interpreted - what formatting
language, or maybe it should just be a reference into the source
code ( going back to the literate programming idea. )
> > (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?
>
Here I was thinking of the short one-line descriptions. The default
help procedure on a module would generate something that sort of
looks like the output from a "man -k keyword" , and in pseudo-python,
would be something like:
print module.__doc_paragraph__
for thing in dir(module): print thing.__doc_string__
> > (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.
>
I can imagine that someone might want to document them, but I didn't
want to push it too far. i.e. maybe it shouldn't be done with the
same attribute mechanism as functions,methods and classes.
> > (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.
>
I'm not sure what's needed or wanted, but I was trying to point out
that we want to define something that is open ended.
- Steve Majewski