From cindy@hotxxxmail.com Sat Jun 13 20:09:43 1998 From: cindy@hotxxxmail.com (cindy@hotxxxmail.com) Date: Sat, 13 Jun 1998 15:09:43 -0400 (EDT) Subject: [Doc-SIG] Hey Girly Girl Message-ID: Hello Cuz Hey girly girl hows it going? I love CA and I love my new job. Remember no telling mom and Dk about it they would kill me if they found out I was doing nude modeling over the net. Hey I showed them your picture and they said that they would hire you. Anyway come look at my web page and tell me what you think. The site is http://www.livesexplus.com go to models info you will love my personal page. Tell me what you think of my name? Anyway gotta go and I will write you later give me a call if you wanna come out. Love Cinthy From Daniel.Larsson@vasteras.mail.telia.com Thu Jun 18 18:54:28 1998 From: Daniel.Larsson@vasteras.mail.telia.com (Daniel Larsson) Date: Thu, 18 Jun 1998 19:54:28 +0200 Subject: [Doc-SIG] Documentation tool Message-ID: <000001bd9ae2$246dbd60$07bc43c3@telia.com> Hi everyone, I recently spent some time rewriting gendoc from scratch, trying to incoprorate some of the ideas I, Robin and some people on this group sketched out. I've only just started, so you won't find any working code, but I've put up a snapshot at http://starship.skyport.net/crew/danilo/pythondoc/pythondoc.zip There's also an HTML page trying to describe what I've done at http://starship.skyport.net/crew/danilo/pythondoc/pythondoc.html If you are interested in this, and have some spare time :-), please give it a glance and contribute your ideas, suggestions, code, whatever. We discussed cross references a couple of months ago, which I haven't started implementing yet. There are some issues I'd like people's opinions/ideas on. One of the ideas that popped up was an extensible crossreference model, which sounds great. One of the issues is how the cross reference modules and the formatters (extensions generating docs in various formats) should communicate. Also, I'd like people's opinions on what information should go into the abstract doctree. Take a look at the "output.txt" file in the .zip file. At the end is the doctree dumped in a XML-like format. I might not be as responsive as I'd like over the weekend, since we're celebrating midsummer's eve tomorrow here in Sweden... :-) /Daniel Larsson From johnm@magnet.com Thu Jun 18 19:10:24 1998 From: johnm@magnet.com (John Mitchell) Date: Thu, 18 Jun 1998 14:10:24 -0400 (EDT) Subject: [Doc-SIG] Documentation tool In-Reply-To: <000001bd9ae2$246dbd60$07bc43c3@telia.com> Message-ID: On Thu, 18 Jun 1998, Daniel Larsson wrote: > Hi everyone, > > I recently spent some time rewriting gendoc from scratch, trying to > incoprorate some of the ideas I, Robin and some people on this group > sketched out. I've only just started, so you won't find any working > code, but I've put up a snapshot at > > http://starship.skyport.net/crew/danilo/pythondoc/pythondoc.zip > > There's also an HTML page trying to describe what I've done at > > http://starship.skyport.net/crew/danilo/pythondoc/pythondoc.html > > If you are interested in this, and have some spare time :-), please > give it a glance and contribute your ideas, suggestions, code, whatever. > > We discussed cross references a couple of months ago [...] Perhaps this is a silly question, but why not just copy Javadoc's conventions? It already handles cross references, embedded HTML, its easy, and a few zillion people already use it. - j From MHammond@skippinet.com.au Fri Jun 19 00:44:31 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Fri, 19 Jun 1998 09:44:31 +1000 Subject: [Doc-SIG] Documentation tool Message-ID: <0bc501bd9b15$bbcaa3c0$0a01a8c0@skippy.skippinet.com.au> I dont know what they are. Is it possible to summarize? Thanks, Mark. -----Original Message----- From: John Mitchell To: Daniel Larsson Cc: DOC-SIG Date: Friday, 19 June 1998 4:16 Subject: Re: [Doc-SIG] Documentation tool >On Thu, 18 Jun 1998, Daniel Larsson wrote: >Perhaps this is a silly question, but why not just copy Javadoc's >conventions? It already handles cross references, embedded HTML, its >easy, and a few zillion people already use it. From johnm@magnet.com Fri Jun 19 15:43:38 1998 From: johnm@magnet.com (John Mitchell) Date: Fri, 19 Jun 1998 10:43:38 -0400 (EDT) Subject: [Doc-SIG] Documentation tool In-Reply-To: <0bc501bd9b15$bbcaa3c0$0a01a8c0@skippy.skippinet.com.au> Message-ID: On Fri, 19 Jun 1998, Mark Hammond wrote: > 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: /** * A class representing a window on the screen. * For example: * 
      *    Window win = new Window(parent);
      *    win.show();
      *
* * @see awt.BaseWindow * @see awt.Button * @version 1.2 12 Dec 1994 * @author Sami Shaio */ class Window extends BaseWindow { ... } More info can be had at: http://www.javasoft.com/products/jdk/javadoc/index.html I like javadoc because it's trivially easy to get your scribbled comments into nice crosslinked HTML pages, so the code author tends to comment his/her code better, leading to more reuse, etc. Documentation is a drag to write. Why spend braincells on a new formatting system, when an already-designed one is up and happening? I write java a bit, and I'd *really* like a Python flavor of it... - j From bsd@scripps.edu Sat Jun 20 00:00:29 1998 From: bsd@scripps.edu (Bruce Duncan) Date: Fri, 19 Jun 1998 16:00:29 -0700 (PDT) Subject: [Doc-SIG] documentation for packages Message-ID: Greetings, What are the conventions, tips, tricks, etc., for using gendoc with python packages? It seems that packages with the same sub-package name, e.g, imaging.io and telecom.io, causes a problem withe the default naming scheme. Also, what is the role of the __init__.py file with respect to package documentation and gendoc? Thanks, -bsd- Bruce Duncan The Scripps Research Institute bsd "is located at" scripps "in the domain" edu # anti spam... From MHammond@skippinet.com.au Sat Jun 20 04:01:06 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Sat, 20 Jun 1998 13:01:06 +1000 Subject: [Doc-SIG] Documentation tool Message-ID: <0cce01bd9bf8$cd0e8f00$0a01a8c0@skippy.skippinet.com.au> >> 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. From guido@CNRI.Reston.Va.US Mon Jun 22 17:07:07 1998 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 22 Jun 1998 12:07:07 -0400 Subject: [Doc-SIG] Documentation tool In-Reply-To: Your message of "Sat, 20 Jun 1998 13:01:06 +1000." <0cce01bd9bf8$cd0e8f00$0a01a8c0@skippy.skippinet.com.au> References: <0cce01bd9bf8$cd0e8f00$0a01a8c0@skippy.skippinet.com.au> Message-ID: <199806221607.MAA04716@eric.CNRI.Reston.Va.US> > 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. Hm... I've read plenty of Java code and have no problem with its markup of doc comments. Perhaps we could reconsider this? --Guido van Rossum (home page: http://www.python.org/~guido/) From John Mitchell Mon Jun 22 17:09:20 1998 From: John Mitchell (John Mitchell) Date: Mon, 22 Jun 1998 12:09:20 -0400 (EDT) Subject: [Doc-SIG] Documentation tool In-Reply-To: <0cce01bd9bf8$cd0e8f00$0a01a8c0@skippy.skippinet.com.au> Message-ID: On Sat, 20 Jun 1998, Mark Hammond wrote: > >> 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). woo-woo! After getting nary a hit w/ Python.org's search engine, I found "doc.py version 0.8" at http://starship.skyport.net/~lemburg/Software.html Is this what you're talking about? Doesnt seem to handle any javadoc-isms, like @see... So, where's "autodoc" at? > 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. - j From friedrich@pythonpros.com Mon Jun 22 17:33:11 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Mon, 22 Jun 1998 11:33:11 -0500 Subject: [Doc-SIG] Documentation tool Message-ID: <199806221630.JAA25481@ns1.lyra.org> > From: John Mitchell > To: Mark Hammond > > > 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 From guido@CNRI.Reston.Va.US Mon Jun 22 18:56:35 1998 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Mon, 22 Jun 1998 13:56:35 -0400 Subject: [Doc-SIG] Documentation tool In-Reply-To: Your message of "Mon, 22 Jun 1998 11:33:11 CDT." <199806221630.JAA25481@ns1.lyra.org> References: <199806221630.JAA25481@ns1.lyra.org> Message-ID: <199806221756.NAA05007@eric.CNRI.Reston.Va.US> > 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) As long as it's a well-defined subset of HTML tags that can be used (e.g. , and ) I don't mind -- that's easily parseable. --Guido van Rossum (home page: http://www.python.org/~guido/) From friedrich@pythonpros.com Tue Jun 23 04:52:17 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Mon, 22 Jun 1998 21:52:17 -0600 Subject: [Doc-SIG] Documentation tool References: <006b01bd9e3e$b720e830$0a01a8c0@skippy.skippinet.com.au> Message-ID: <358F266A.5BB089D1@pythonpros.com> Mark Hammond wrote: > 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. The problem I see cropping up is people thinking that words implies full HTML (people never read the instructions). It's a real slippery slope that I wanted to avoid. If you're only going to have two or three tag out of the HTML then it shouldn't matter that they are same or not since you are not adopting the bulk of the markup. Next people will want
  • support, and then ... yada yada. Oh and I can see someone arguing that should be supported instead/as well as because it's the proper abstract tag. Whoops, slipped on that ice again! """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 RFC 4981. """ Hmmm. I'm sorry I still prefer the former. -Robin From MHammond@skippinet.com.au Tue Jun 23 04:30:50 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 23 Jun 1998 13:30:50 +1000 Subject: [Doc-SIG] Documentation tool Message-ID: <010b01bd9e57$53dd3030$0a01a8c0@skippy.skippinet.com.au> >"""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 RFC 4981. >""" > >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 |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. From MHammond@skippinet.com.au Tue Jun 23 02:27:42 1998 From: MHammond@skippinet.com.au (Mark Hammond) Date: Tue, 23 Jun 1998 11:27:42 +1000 Subject: [Doc-SIG] Documentation tool Message-ID: <00d601bd9e46$235b5790$0a01a8c0@skippy.skippinet.com.au> >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 or . Thus you may have a comment "@comm This is very similar to 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) * tags are _not_ used, as there is no way to know the final URL of anything. Something like the 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. From dlarsson@sw.seisy.abb.se Tue Jun 23 08:12:54 1998 From: dlarsson@sw.seisy.abb.se (Daniel Larsson) Date: Tue, 23 Jun 1998 09:12:54 +0200 Subject: [Doc-SIG] Documentation tool Message-ID: <01bd9e76$5795b340$3516dd8a@pc033500.sw.seisy.abb.se> 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": Does some fooey stuff. None Bla bla bla. 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 >>itemA relates to itemB only on the first Monday of >the month as >>documented in RFC >4981. >>""" >> >>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 |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 > > > From doughellmann@mindspring.com Tue Jun 23 15:00:40 1998 From: doughellmann@mindspring.com (Doug Hellmann) Date: Tue, 23 Jun 1998 09:00:40 -0500 Subject: [Doc-SIG] Documentation tool References: <01bd9e76$5795b340$3516dd8a@pc033500.sw.seisy.abb.se> Message-ID: <358FB505.D73C6CA6@mindspring.com> 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 |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-- From jim.fulton@Digicool.com Tue Jun 23 14:30:43 1998 From: jim.fulton@Digicool.com (Jim Fulton) Date: Tue, 23 Jun 1998 09:30:43 -0400 Subject: [Doc-SIG] Documentation tool References: <010b01bd9e57$53dd3030$0a01a8c0@skippy.skippinet.com.au> Message-ID: <358FAE03.3CFE@digicool.com> 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 > >itemA relates to itemB only on the first Monday of > the month as > >documented in RFC > 4981. > >""" > > > >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. 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 |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. From guido@CNRI.Reston.Va.US Tue Jun 23 15:06:41 1998 From: guido@CNRI.Reston.Va.US (Guido van Rossum) Date: Tue, 23 Jun 1998 10:06:41 -0400 Subject: [Doc-SIG] Documentation tool In-Reply-To: Your message of "Mon, 22 Jun 1998 21:52:17 MDT." <358F266A.5BB089D1@pythonpros.com> References: <006b01bd9e3e$b720e830$0a01a8c0@skippy.skippinet.com.au> <358F266A.5BB089D1@pythonpros.com> Message-ID: <199806231406.KAA11242@eric.CNRI.Reston.Va.US> > The problem I see cropping up is people thinking that words > implies full HTML (people never read the instructions). It's a real > slippery slope that I wanted to avoid. If you're only going to have > two or three tag out of the HTML then it shouldn't matter that they > are same or not since you are not adopting the bulk of the markup. > Next people will want
    • support, and then ... yada yada. > Oh and I can see someone arguing that should be supported > instead/as well as because it's the proper abstract tag. Whoops, > slipped on that ice again! What happened to JavaDoc? Did this happen? How much of HTML does it support? Is there pressure to support more? --Guido van Rossum (home page: http://www.python.org/~guido/) From friedrich@pythonpros.com Tue Jun 23 15:21:07 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Tue, 23 Jun 1998 09:21:07 -0500 Subject: [Doc-SIG] Documentation tool Message-ID: <199806231511.IAA30225@ns1.lyra.org> ---------- > From: Guido van Rossum > > 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) From friedrich@pythonpros.com Tue Jun 23 16:20:05 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Tue, 23 Jun 1998 10:20:05 -0500 Subject: [Doc-SIG] Documentation tool Message-ID: <199806231517.IAA30253@ns1.lyra.org> ---------- > From: Jim Fulton > > Mark Hammond--- > > class Foo: > > """Docstring describing verbosely what the class is for.""" > > def __init__(self, > > parent, # @parm |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? From Fred L. Drake, Jr." References: <199806231511.IAA30225@ns1.lyra.org> Message-ID: <13711.51398.646659.775876@weyr.cnri.reston.va.us> Robin Friedrich writes: > > How much of HTML does it > > support? Is there pressure to support more? > Already supports all of it I think. (yuk) When I last looked at javadoc, this seemed to be "pass-through" support; there was nothing that understood any of it. Which tells me that (that aspect of) javadoc is broken. ;-) -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From Fred L. Drake, Jr." References: <199806231517.IAA30253@ns1.lyra.org> Message-ID: <13711.51585.269180.221620@weyr.cnri.reston.va.us> Robin Friedrich writes: > 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. So call it version 2.0. ;-) Seriously, I have a couple of (contradictory) thoughts on this. On the one hand, a language change will be necessary to support per-parameter docstrings, and something could probably done such that the basic syntax can be shared with an optional type declaration scheme. The parameter docstrings can be made available both at runtime using import and by parse-based methods. On the other hand, I'm increasingly leaning toward separate documentation. As tedious as it can be, I don't find documentation sprinkled throughout my code desirable, mostly because it obfuscates the code as well as documents it. (This is *not* an argument to not support "inline" documentation; clearly both approaches can be used in parallel.) I like docstrings, but mostly use them as a brief refresher on the interface to a class or module; this is only part of what I look for in reference documentation. Making language changes to support elaborate forms of documention becomes less important here. See also below.... > 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? The other big reason I'm not of the mind to spend a lot of effort on docstring-based reference documentation is that Python is simply too dynamic for *either* of these approaches to be really effective in the general case. While most modules may be just fine with either approach, there's no way to always get it "right". Consider: try: import Foo except ImportError: def func(): """Bogus operation.""" pass else: def func(): """Do something really neat.""" pass What goes in the documentation? This really doesn't seem like an unusual circumstance, so the import-based methods (potentially) generate different documentation based on whether sys.path is right (imagine the user got PYTHONPATH wrong), and the parse-based approach has to make an arbitrary decision, still possibly based on being able to locate Foo.py (or Foo.dll, or Foo.so, or Foomodule.so, or ...). Don't get me wrong: I still think that improved conventions and tools can help the current situation. Allowing parameter docstrings ("parmstrings"? ;) would definately be an improvement. -Fred -- Fred L. Drake, Jr. Corporation for National Research Initiatives 1895 Preston White Dr. Reston, VA 20191 From klm@python.org Tue Jun 23 17:08:13 1998 From: klm@python.org (Ken Manheimer) Date: Tue, 23 Jun 1998 12:08:13 -0400 (EDT) Subject: [Doc-SIG] Lost maillist messages thursday eve (6/18) to friday noon (6/19) Message-ID: <199806231608.MAA13089@glyph.cnri.reston.va.us> 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@python.org 703 620-8990 x268 (orporation for National Research |nitiatives # If you appreciate Python, consider joining the PSA! # # . # From tim_one@email.msn.com Tue Jun 23 17:08:28 1998 From: tim_one@email.msn.com (Tim Peters) Date: Tue, 23 Jun 1998 12:08:28 -0400 Subject: [Doc-SIG] Documentation tool In-Reply-To: <199806231406.KAA11242@eric.CNRI.Reston.Va.US> Message-ID: <000101bd9ec1$29065700$2d2a2399@tim> > What happened to JavaDoc? Did this happen? How much of HTML does it > support? Is there pressure to support more? javadoc only worries about its own tags (@param and @see and so on); everything else is passed thru, unanalyzed, to its output (which is a web of HTML files -- a browser is an essential part of the javadoc system). So javadoc "supports" all of HTML (present & future) in user docs simply by leaving it alone. The only restriction is that javadoc reserves the heading tags (

      ,

      , etc) for its own use. The user *could* use heading tags too (javadoc won't try to stop them -- it's not trying to analyze the user's HTML so doesn't even notice), but the result would be confusing to look at. It's a lovely separation of concerns, but not at all designed for any sort of introspective or interactive use. if-all-you-want-is-to-stare-at-your-browser-it's-great-ly y'rs - tim From Edward Welbourne Tue Jun 23 21:05:36 1998 From: Edward Welbourne (Edward Welbourne) Date: Tue, 23 Jun 1998 21:05:36 +0100 Subject: [Doc-SIG] Documentation tool In-Reply-To: <13711.51585.269180.221620@weyr.cnri.reston.va.us> References: <199806231517.IAA30253@ns1.lyra.org> <13711.51585.269180.221620@weyr.cnri.reston.va.us> Message-ID: <199806232005.VAA22320@lsls4p.lsl.co.uk> As someone fare more eloquent once said ... sorry this is so long, but I don't have time to shorten it. The really unstoppable reason I prefer import-based handling of doc strings is that *it means there is only one parser for python code*. The significance of that to me is like a religious thing, so I'll remember to tolerate other views but *I know it's right* ;^> Recent discussion has had a lot of stuff about comments, docstrings and generating reference manuals. I have strong opinions, I hope they can be made useful. There are three kinds of `documentation' I want associated with a tool: comments -- which I read when I'm modifying the tool manuals -- which I read before trying to write code which uses the tool docstrings -- which I read when I find the tool in my hands The first is like a bar-code on goods in a shop - the shop needs it there, but the customer doesn't look at it; the second is like the information on the packaging, the shop has to provide it and the customer is only going to read it once; the last is the few simple things etched on the article itself - the things that will remind me of all the important bits when I'm using the goods. When I want to know which tool to use, I consult the manual: and I'm happy enough to have an autogenerated rendition of the docstrings in the manual (as an appendix), but the thing I want the manual for is to guide me from `I know what I want to do' to `here are the tools to do it'. When I'm running my code in a debugger and it's carrying around objects from someone else's package, I probably don't know much about how those objects behave. If they're not doing what I expect of them, I need to be able to ask them about themselves. In python, I can ask for information about which package provided them, so I could RTF sources and work out what's going on: but one hacker's beautiful code is another's spaghetti forgetti. If I can ask the object itself to tell me about itself, I'm much happier - if only because I can then tell the difference between a bug in the tool I'm using and a gap between my expectations and the tools's designer's intent. I can't fix (or enhance) the tool without making sense of its source: and that's when I need the comments. They tell me why the code does things the way it does, they can contain warnings about silly mistakes I might introduce if I try to do the obvious, and they're where I'm going to leave the information that it was me who changed it, and why. Consequently, comments belong within the source code and should be (ignored and) thrown away by the parser - which is what most sensible programming languages do, albeit with some bodges here and there. manuals belong without the source code; they should have sophisticated indexes, glossaries, etc.; they even have a right to worry about being pretty; the manual is not part of the program, though it is part of the installation. docstrings need to be attached to objects when they're running, so they have to have a presence in the source code (though they may legitimately be *constructed* at run-time) and be recognised by the language. and I don't want any of them intruding on the others' territory: docstring information shouldn't be taking up comment space (though I accept that tagging arguments with `type information' in comments would be a lot better than an incompatible change in the parser to fit that information into the code) and documentation derived from docstrings should be kept to the appendices of the manual. [If you don't sit down and write a manual, you won't have a good manual.] In particular, the parser shouldn't tamper with the value of __doc__, least of all for the sake of a few comments (which it might have misunderstood). The parser does already extract some information (prototype and `where is the source for this', at least) and store it in namespaces. It could do some similar things with `comments as type information', but would have to mistrust this (essentially because we don't want the parser throwing out code just because its comments are wrong). It could get better information, of this kind, from assertions in the code: which are an extant python feature capable of much richer information than mere type and default - eg stipulating relationships among the arguments. Tools can be built (indeed, I think the gendoc folk have done so) for presenting such `gleaned' information in a helpful form at runtime, possibly combined with __doc__ strings. (Another possibly valuable ingredient, by the way, is information extracted from assertions at the start of a function -- I'd trust these a lot better than the comments.) I regard the combination as docstrings. The reason I don't have much time for comments contributing to docstrings (aside from the fact that this isn't what they're for and it would intrude in what they are for) is that, if we can agree the semantics of the comments, we could surely as readily agree the necessary semantics for the structured text format used in __doc__ strings, which are the proper home of this information. That said, I confess the case of `type-tags' on arguments forms a pretty good case for one exception - because they evade repetition of the argument names. If we do tie such documentation to the argument, how am I going to access it ? The arguments of a function aren't accessible from any other namespace ... and what *object* would be carrying this `argdoc string' ? As partial answer to that, we could have the function carry around a dictionary of interface docstrings, func.__ifdocs__ say, whose keys are argument names, values are argdoc strings (or possibly some kind of datastructure packaging those along with default, argument number, ...); special key '' means the function's return value. Anyway, here's a suggestion about specifying arguments in __doc__ - since I don't like docstring info in comments, I have to at least offer a suggestion: in the structured text format (STF hereafter, URL is http://www.cwi.nl/www.python.org/sigs/doc-sig/) there's a convention that any `paragraph' (as there defined) ending in the word `example', in any case, with optional trailing s and punctuators, introduces some text which should be presented `as is' (subject to the usual rules for rationalising leading whitespace on lines); likewise, we could have any paragraph ending in `argument' have a similar behaviour, only it's expecting to introduce a descriptive list (so the magic might only happen if that's what does follow). We almost certainly *do* need some sensible markup rules (not yet in the STF last time I checked) for delimiting the details of an argument: but the basics of a descriptive list should do us pretty well. To my mind, comments are directed at the code's maintainer *and no-one else*, whereas the docstring is the interface specification - the contract between the code's maintainer and the code's user. I don't care how convenient blurring that is for who, that separation is Important: as the author of code calling yours, I want to be able to look at the doc string and know what I'm allowed to assume about what your tools will do for me; that's the bit that I'm trusting you to continue honouring from this version into the next (and that's where I expect you to tell me that you intend to retire one of the arguments at a later version); again as that author, I don't want to have to RTF source and work out which bits are directed at me, which at the maintainer's colleagues as the maintainer of my code, I want folk to call it assuming that it does everything it claims to do, and assuming nothing else. Boring facts of experience say that: folk who had to flick through the code of the implementation come away thinking they know better than the interface documents. They then *don't* call it with some arguments it should accept (because they've discovered it doesn't cope), so I don't get bug reports that I need; and they *do* call it with arguments it never promissed to take, so I get to field false bug reports when I come to make changes within the interface spec I published. 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. From friedrich@pythonpros.com Tue Jun 23 22:13:19 1998 From: friedrich@pythonpros.com (Robin Friedrich) Date: Tue, 23 Jun 1998 16:13:19 -0500 Subject: [Doc-SIG] Documentation tool Message-ID: <199806232110.OAA31527@ns1.lyra.org> > 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.