[Doc-SIG] Documentation tool

[Daniel Larsson]

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 will result in a tree corresponding roughly to this "XML":

<Function id="foo">
  <Oneliner>Does some fooey stuff.</Oneliner>
  <Arguments>
    <Argument id="arg1"/>
    <Argument id="arg2">
        <Default>None</Default>
    </Argument>
  </Arguments>
  <Description>
    Bla bla bla.
  </Description>
</Function>

Hopefully it will be flexible enough to let people write code that parses
source files
for "in code" comments and incorporate it into the framework (hint,
hint...).

>-----Original Message-----
>From: doc-sig-admin@python.org [mailto:doc-sig-admin@python.org] On
>Behalf Of Mark Hammond
>Sent: den 23 juni 1998 05:31
>To: friedrich@pythonpros.com
>Cc: DOC-SIG
>Subject: Re: [Doc-SIG] Documentation tool
>
>
>>"""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.
>
>
>_______________________________________________
>Doc-SIG maillist  -  Doc-SIG@python.org
>http://www.python.org/mailman/listinfo/doc-sig
>
>
>