Mailman 3 June 1998 - Doc-SIG

Re: [Doc-SIG] Documentation tool
by Robin Friedrich June 23, 1998

June 23, 1998

> I want to keep comments and doc-strings separate. > > By the by: what were the eventual conclusions of all that discussion > about how to specify cross-references in docstrings ? Is there a > succinct statement of it somewhere ? > > Eddy. http://starship.skyport.net/crew/danilo/pythondoc/pythondoc.htm Click the second footnote. Pipermail can show the whole thread as well.

1 0

Re: [Doc-SIG] Documentation tool
by Robin Friedrich June 23, 1998

June 23, 1998

---------- > From: Jim Fulton <jim.fulton(a)Digicool.com> > > Mark Hammond--- > > 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. I vaguely remember this discussed last year. This implies changes to the language; but requiring everyone to use a newer version (~1.6) seems weak. (Original requirements, admittedly only drafted by me, stipulated 1.5 compatibility.) I would agree that it would be good to have this information at runtime. But without a change to the language we are back to the doc-string again. > > > 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. The pythondoc approach is to populate a DOM with info gathered "by some means" and then pass that structure to a thing that renders it in a user specified manner. Order is no longer the important factor. We could just as well plug in some auxiliary source parsing to pick up argument attributes and populate the DOM as Daniel mentioned. Thus autoduck can have a nest;-) I hate to rehash this but this brings up the age old debate over parsing vs. import/introspection. The intent is to support both Python source and C extension code. What are the scenarios for usage guys? How much info is gathered via import vs gathered via a parser?

3 2

Re: [Doc-SIG] Documentation tool
by Mark Hammond June 23, 1998

June 23, 1998

Before I reply to this whole thing in detail :-) >I still dislike the idea of placing HTML directly in the body to provide >either markup () or references. (javadoc is way too HTML oriented for >my taste) I like the gendoc standards for this; i.e. **words** and *words* >and the .. href expansions at the bottom. So I guess we would have a mixed >bag but not to the point of irritation. Is this a good compromise? It should be noted that (all?) early versions of autodoc had never heard of HTML - well, at least did not output it. Certainly, the autodoc tool I use still does not support HTML (and probably never will) - the tag is a generic "bold" tag that in my case, maps to WinHelp's bold command. We could just view some of the tags as being a coincidence they are similar to HTML... The particular tool I use happens to use "<" for tag delimiters, and shares one or 2 with HTML (B and I being about it). Apart from that it is not at all like HTML. Mark.

4 3

Lost maillist messages thursday eve (6/18) to friday noon (6/19)
by Ken Manheimer June 23, 1998

June 23, 1998

Some of you may have lost postings posted to one of the following maillists between last thursday (6/18) evening and friday (6/19) noon. Mailman-Developers (1 msg) Matrix-SIG (8 msgs) DB-SIG (3 msgs) Doc-SIG (4 msgs) Pythonmac-SIG (3 msgs) XML-SIG (1 msg) Trove-Dev (6 msgs) This happened accompanying an upgrade of our maillist software, mailman, due to an bad interaction between a new mailman feature and an anti-spam (anti-relay) mechanism applied to python.org's sendmail configuration. This problem did not show during testing because our test recipients were all local, and not subject to the anti-relay constraints. If you sent something to any of these lists during that time frame and never saw it show, you may want to resend. Archiving was not affected, so you should be able to find the messages in the maillist archives. People receiving the lists in digest format were not affected, since the delivery problem was fixed before the digest delivery time. My apologies for the disruption! Ken Manheimer klm(a)python.org 703 620-8990 x268 (orporation for National Research |nitiatives # If you appreciate Python, consider joining the PSA! # # <http://www.python.org/psa/>. #

1 0

Re: [Doc-SIG] Documentation tool
by Robin Friedrich June 23, 1998

June 23, 1998

---------- > From: Guido van Rossum <guido(a)CNRI.Reston.Va.US> > > What happened to JavaDoc? It's still on the table. > Did this happen? Not yet. The @param and @see stuff seems helpful though. > How much of HTML does it > support? Is there pressure to support more? Already supports all of it I think. (yuk)

2 1

Re: [Doc-SIG] Documentation tool
by Daniel Larsson June 23, 1998

June 23, 1998

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(a)python.org [mailto:doc-sig-admin@python.org] On >Behalf Of Mark Hammond >Sent: den 23 juni 1998 05:31 >To: friedrich(a)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 >>itemA relates to itemB 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 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(a)python.org >http://www.python.org/mailman/listinfo/doc-sig > > >

2 1

Re: [Doc-SIG] Documentation tool
by Mark Hammond June 23, 1998

June 23, 1998

>"""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 >itemA relates to itemB 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 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.

2 1

Re: [Doc-SIG] Documentation tool
by Mark Hammond June 23, 1998

June 23, 1998

>Hm... I've read plenty of Java code and have no problem with its >markup of doc comments. Perhaps we could reconsider this? Yay!! :-) Ive been thinking about this for quite a number of years now - ever since I started the reference documentation in Pythonwin (which is getting quite complete!). I see gendoc as a very useful tool, but IMO targetted at a different "audience" than the autodoc style of documentation. The main "features" of autodoc that make it particularly suitable to "reference" guides is: * It reorders your input tags. For example, dispersed through out your implementation of a single function, you may have comments like "@see something" and "@see thistoo". These may be intermingled with other marked up documentation. When the documentation is produced, there is a single "See Also" section with all the "@see" references rendered. Basically, the format of the output if defined externally, and quite independent of the input ordering. This makes for consistent and professional reference guides. * Many of the "links" are implicit. In the example above, a "@see something" does not require any tags to make it into a hyperlink. The "@see" tag is defined as taking a single object reference (ie, a name, not a phrase). Therefore, autoduck renders the "See Also" section with Hyperlinks if it can resolve the name, otherwise renders it it as normal text. * Hyperlinks may be explicit. The autodoc I use uses a format <o objectname> or <om [object.]method>. Thus you may have a comment "@comm This is very similar to <om othermethod> but a bit different" In this case, a "Comments" section will appear in the final output, and all "@comm" paragraphs rendered there (with tags resolved) * <a> tags are _not_ used, as there is no way to know the final URL of anything. Something like the <a tag _could_ be used for external Web references, but that is about all. * Many "@" tags are optional. Eg, "@parm" tags may be used, but if they dont exist, autodoc is capable of extracting at least default info from parsing the C sources. Obviously Python makes this even easier. This is quite different from the goals of gendoc, which to my mind are more suited to all documentation other then reference guides :-) gendoc allows you to structure tutorial, or introductory type material. It is far far better at this than autodoc. IMO, the general structure of autodoc makes for far better reference guides. Also, I see this fitting beautifully (nearly :-) with gendoc. gendoc handles the docstrings, and autosnake uses Python comments. Ahh - so many ideas, so little time :-( Mark.

1 0

Re: [Doc-SIG] Documentation tool
by Robin Friedrich June 22, 1998

June 22, 1998

> From: John Mitchell <johnm(a)magnet.com> > To: Mark Hammond <MHammond(a)skippinet.com.au> > > > When I suggested something like this a while ago to the DOC SIG, the > > consensus was that it does not scan well enough for humans. People > > thought that the doc strings should be less intrusive than that. > > I dont agree. I want low-hassle input that makes for pretty output, with > cross-language support. "@see" isnt bad, but magic parsing (a la Jim > Fulton) doesnt do it for me. > Having looked at the javadoc man page it seems reasonable. Much of it though is unnecessary as pythondoc can infer much from the module environment. I would say that @see, @return, @param in particular would be useful for definitively marking the docstring. Structured text, which is good for paragraph, bullet and heading formation, is lacking when it comes time to define your parameters. A convention is needed. I still dislike the idea of placing HTML directly in the body to provide either markup () or references. (javadoc is way too HTML oriented for my taste) I like the gendoc standards for this; i.e. **words** and *words* and the .. href expansions at the bottom. So I guess we would have a mixed bag but not to the point of irritation. Is this a good compromise? -Robin

2 1

Re: [Doc-SIG] Documentation tool
by Mark Hammond June 22, 1998

June 22, 1998

>> I dont know what [JavaDoc formatting is like]. Is it possible to >> summarize? > >Yep. You start a comment with "/**" (instead of "/*", and add in a few >magic tags. As in: This is almost identical to "autodoc", the tool I wrote about before to the SWIG List (Ive suggested that SWIG generate this sort of documentation directly in the sources). When I suggested something like this a while ago to the DOC SIG, the consensus was that it does not scan well enough for humans. People thought that the doc strings should be less intrusive than that. But FWIW, I tend to agree with you. My stated philosophy is that I will sacrifice some readability in the source code comments if the result is superior documentation - which I think this would provide. And another FWIW, I have literally _thousands_ of lines of C code all documented in this format (which is what builds the Windows help files). So whatever the DOC SIG does, I will always keep this format around for something :-) Mark.

3 2