[Doc-SIG] Documentation tool

[Doug Hellmann]

This is a multi-part message in MIME format.
--------------2583F65E996AAA9935E47343
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Daniel Larsson wrote:
> 
> Yes, I agree it is preferrable to document things as close as possible to
> the source. What I did in my current experiments regarding argument
> documentation is basically this:
> 
> def foo(arg1, arg2=None):
>     '''Does some fooey stuff.
> 
>     Bla bla bla.
> 
>     Arguments:
> 
>       arg1 -- Pass in whatever you want here.
> 
>       arg2 -- Throw in something you don't like here.
>     '''
>     pass


This is something like the format I've been using in my code, too.  But why
does Python stop at __doc__ strings for methods/functions?  Why not have
individual __doc__ strings for arguments as well?  Would this cause too much
confusion with arguments which have default string values?

Something like this would make it easier to associate descriptions with each
argument in a way that makes documentation preparation easier and would also
open up more information to interactive environments like Pythonwin, the Mac
PythonIDE, PTUI, etc.

def foo(arg1 'Pass in whatever you want here', arg2=None 'Throw in something
you do not like here'):
	''' Does some fooey stuff.

	Bla bla bla.
	'''
	pass

And it seems much more natural and Pythonesque than 'hiding' the information
in comments as shown in the previous example.

> >
> >class Foo:
> >  """Docstring describing verbosely what the class is for."""
> >  def __init__(self,
> >                       parent, # @parm <o Window>|The parent window
> >                       style,    # @parm int|Window style.  This
> >*must* not be 0
> >                       )
> >         #@ comm Only call this function when the sun is shining.
> >Otherwise
> >         # an assetion will be raised.
> >         assert SunShining(), "Sun not shining"
> >         self.SomeFunc() # @see SomeFunc
> >         return a,b,c # @rdesc The result is a tuple of a,b,c,
> >unless the moon is full.

I'm not sure what to do with the @see and @rdesc values though.  Could return
have a __doc__ string?  That might be contrived.  

I guess my point is, can we build some more complete documentation features
right into the language, so that it becomes easier to write tools to process
that documentation.

Doug
--------------2583F65E996AAA9935E47343
Content-Type: text/x-vcard; charset=us-ascii; name="vcard.vcf"
Content-Transfer-Encoding: 7bit
Content-Description: Card for Doug Hellmann
Content-Disposition: attachment; filename="vcard.vcf"

begin:          vcard
fn:             Doug Hellmann
n:              Hellmann;Doug
email;internet: doughellmann@mindspring.com
x-mozilla-cpt:  ;0
x-mozilla-html: FALSE
version:        2.1
end:            vcard


--------------2583F65E996AAA9935E47343--