[Doc-SIG] Documentation tool

[Mark Hammond]

>"""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.

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.)

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.

Mark.