[Doc-SIG] Documentation tool

[Jim Fulton]

Mark Hammond wrote:
> 
> >"""I'm typing along in my neat little doc string and I want to note
> that
> >*itemA* relates to *itemB*  only on the first Monday of the month
> as
> >documented in [RFC 4981].
> >
> >.. [RFC 4981] http://www.w3c.org/mystical/magic.html
> >"""
> >
> >or
> >
> >"""I'm typing along in my neat little doc string and I want to note
> that
> ><I>itemA</I> relates to <I>itemB</I>  only on the first Monday of
> the month as
> >documented in <A HREF="http://www.w3c.org/mystical/magic.html">RFC
> 4981</A>.
> >"""
> >
> >Hmmm.  I'm sorry I still prefer the former.
> 
> I think we are slightly at cross-purposes.  I have no problem with
> deciding on a concept that replaces <B> etc with *, but that is not
> the real point.

Good! :-)
 
> I suppose Im considering something like this
> (ignore the style for now - block comments are useful for this
> stuff.)
> 
> -- module foo.py
> """ docstring describing the concepts behind foo, some examples,
> etc.
> 
>   Introduction
>     structured text, as for now
> 
>   Examples
>     etc
> 
> """
> 
> 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.
> 
> Now, this obviously contrived example appeals much more to me than
> attempting to write it up correctly in the docstring.  Even though
> the docstring is close to the code, it is not close enough.  Having
> it _in_ the code makes for more reliable updating (eg, it would be
> quite hard to add a new param to this method without realising you
> should document it.)

I agree that it would be nice to document the arguments directly.
I think it would also be handy to have this information at run 
time, so I'd prefer to go farther than a commenting convention.
Perhaps some sort of argument doc strings could be supported.
Perhaps this could be folded into some syntax for optional
argument typing.
 
> The other benefit is that the generated documentation looks more
> professional.  _Every_ method is documented with identical header
> ordering and grouping, etc.  No need to put stuff in some order that
> you can never remember.
> 
> IMO, trying to maintain a consistent documentation style, and
> keeping it up to date in docstrings wont work anywhere near as well
> as allowing short, cryptic annotations in comments.
> 
> But I also dont see it as a "one or other" approach.  We need
> something that encapsulates both ideas and requirements into the one
> tool.

Well said.

Jim

--
Jim Fulton           mailto:jim@digicool.com
Technical Director   (888) 344-4332              Python Powered!
Digital Creations    http://www.digicool.com     http://www.python.org

Under US Code Title 47, Sec.227(b)(1)(C), Sec.227(a)(2)(B) This email
address may not be added to any commercial mail list with out my
permission.  Violation of my privacy with advertising or SPAM will
result in a suit for a MINIMUM of $500 damages/incident, $1500 for
repeats.