Thread: Doxygen?
I've been playing with the backend code and it is finally starting to make sense. I've discovered the wonders that lie in StringInfo, List and FastList, and suddenly, it's all starting to make sense. I must say, the core of PostgreSQL really is Lisp, and I think that's what makes it rock so much! I've tinkered with modifying the comments so that Doxygen can generate some useful documentation from it. Would you (in the plural sense) be interested in seeing patches to the documentation to make it Doxygen friendly? Would you like to see the Doxyfile I am using, and perhaps incorporate it into the source tree? I'll start posting the documentation I am generating to my vanity site (announcements later), but would this be something that the postgresql.org main site would be able to host? It'll be a bunch of static HTML files. -- Jonathan Gardner jgardner@jonathangardner.net
Jonathan Gardner wrote: > I've been playing with the backend code and it is finally starting to make > sense. I've discovered the wonders that lie in StringInfo, List and > FastList, and suddenly, it's all starting to make sense. I must say, the > core of PostgreSQL really is Lisp, and I think that's what makes it rock so > much! > > I've tinkered with modifying the comments so that Doxygen can generate some > useful documentation from it. Would you (in the plural sense) be interested > in seeing patches to the documentation to make it Doxygen friendly? Would > you like to see the Doxyfile I am using, and perhaps incorporate it into > the source tree? > > I'll start posting the documentation I am generating to my vanity site > (announcements later), but would this be something that the postgresql.org > main site would be able to host? It'll be a bunch of static HTML files. Sure, I would like to see that. -- Bruce Momjian | http://candle.pha.pa.us pgman@candle.pha.pa.us | (610) 359-1001+ If your life is a hard drive, | 13 Roberts Road + Christ can be your backup. | Newtown Square, Pennsylvania19073
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Tuesday 16 March 2004 5:56 pm, Bruce Momjian wrote: > Jonathan Gardner wrote: > > I'll start posting the documentation I am generating to my vanity > > site (announcements later), but would this be something that the > > postgresql.org main site would be able to host? It'll be a bunch of > > static HTML files. > > Sure, I would like to see that. I posted some preliminary documentation at the following URL. This only contains stuff found in src/backend/node and src/include/node. This URL won't be permanent. http://www.jonathangardner.net/PostgreSQL/doxygen/ I formatted and added some documentation for List, FastList, and Node. You can also browse to the list.c, pg_list.h, and nodes.h to see some more of my documentation. Suggestions welcome. I am still new with Doxygen, so if you have any tips, I'm all ears. - -- Jonathan Gardner jgardner@jonathangardner.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.3 (GNU/Linux) iD8DBQFAV/Upqp6r/MVGlwwRAjssAKCl7GaW36qTH5svMlQronc+FzhMYQCeOcwv Vi7AmyIS/pjYUong60sYxfE= =WSfP -----END PGP SIGNATURE-----
> -----Original Message----- > From: Jonathan Gardner [mailto:jgardner@jonathangardner.net] > Sent: 17 March 2004 01:41 > To: pgsql-hackers@postgresql.org > Subject: [HACKERS] Doxygen? > > I'll start posting the documentation I am generating to my > vanity site (announcements later), but would this be > something that the postgresql.org main site would be able to > host? It'll be a bunch of static HTML files. This is not something that should be on the main site, but on developer.postgresql.org. And yes, if there are no objections here then I see no reason why it cannot be added. I assume you will be able to keep it up to date? Regards, Dave.
Folks, this is what greenhorns like me have been waiting for. Great stuff. Keep the faith Zoltan ----- Original Message ----- From: "Jonathan M. Gardner" <jgardner@jonathangardner.net> To: "Bruce Momjian" <pgman@candle.pha.pa.us> Cc: <pgsql-hackers@postgresql.org> Sent: Wednesday, March 17, 2004 7:50 AM Subject: Re: [HACKERS] Doxygen? -----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Tuesday 16 March 2004 5:56 pm, Bruce Momjian wrote: > Jonathan Gardner wrote: > > I'll start posting the documentation I am generating to my vanity > > site (announcements later), but would this be something that the > > postgresql.org main site would be able to host? It'll be a bunch of > > static HTML files. > > Sure, I would like to see that. I posted some preliminary documentation at the following URL. This only contains stuff found in src/backend/node and src/include/node. This URL won't be permanent. http://www.jonathangardner.net/PostgreSQL/doxygen/ I formatted and added some documentation for List, FastList, and Node. You can also browse to the list.c, pg_list.h, and nodes.h to see some more of my documentation. Suggestions welcome. I am still new with Doxygen, so if you have any tips, I'm all ears. - -- Jonathan Gardner jgardner@jonathangardner.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.3 (GNU/Linux) iD8DBQFAV/Upqp6r/MVGlwwRAjssAKCl7GaW36qTH5svMlQronc+FzhMYQCeOcwv Vi7AmyIS/pjYUong60sYxfE= =WSfP -----END PGP SIGNATURE----- ---------------------------(end of broadcast)--------------------------- TIP 6: Have you searched our list archives? http://archives.postgresql.org
I cc'ed the hackers list -- I hope you won't mind. On Wednesday 17 March 2004 02:34 am, Neil Conway wrote: > "Jonathan M. Gardner" <jgardner@jonathangardner.net> writes: > > I formatted and added some documentation for List, FastList, and > > Node. You can also browse to the list.c, pg_list.h, and nodes.h to > > see some more of my documentation. > > Just a heads-up: list.c and pg_list.h will be reimplemented fairly > soon in CVS HEAD (the code isn't committed yet, but there's a > preliminary patch I can send you if you're interested). So if you're > going to spend some time documenting stuff, choosing something else > might be a good place to start (dynahash, maybe?). > Send the patch over. I'd love to see it. I'll add some Doxygen-friendly documentation to it if you don't mind. Shouldn't this be in a branch? It sounds like it's going to be a ton of work, as the interface may change. I'm actually intensely interested in the Query struct right now as I need to understand it to get Materialized Views working right. The List concept is plain enough that I didn't waste much time documenting it -- mostly adding an extra '*' here and there to tell Doxygen that it was documentation and not just a comment. > BTW, per your comment on Lisp-ness: actually, the lispy style of > linked list implementation (cons cells) is the cause of some > performance problems in the backend. It means that both length() and > lappend() are O(n) operations; nconc() is also O(n), and equal() is a > lot slower than it could be (once length() is O(1), we can > immediately reject lists with different lengths as being > non-equal). The linked list rewrite gets rid of FastList (which is > just an ugly performance hack) and replaces the linked list > implementation with a new design that does not use cons cells. We > manage the linked list through a pointer to a separate "List" struct, > rather than merely a pointer to the head node. We also store the > length of the list in the struct. As a result, all the above > operations are now constant time (well, except for equal(), but that > is now significantly faster in the common case). > It looks like the only thing it won't do well is random accesses. That hardly ever happens in PostgreSQL, though, right? -- Jonathan Gardner jgardner@jonathangardner.net
On Wednesday 17 March 2004 12:34 am, Dave Page wrote: > > -----Original Message----- > > From: Jonathan Gardner [mailto:jgardner@jonathangardner.net] > > Sent: 17 March 2004 01:41 > > To: pgsql-hackers@postgresql.org > > Subject: [HACKERS] Doxygen? > > > > I'll start posting the documentation I am generating to my > > vanity site (announcements later), but would this be > > something that the postgresql.org main site would be able to > > host? It'll be a bunch of static HTML files. > > This is not something that should be on the main site, but on > developer.postgresql.org. And yes, if there are no objections here then > I see no reason why it cannot be added. I assume you will be able to > keep it up to date? > I was thinking of writing a cron job to update the CVS tree and then build the documentation (takes about 10 minutes on my computer). Then I could push it to wherever you like. Are we currently maintaining two or three branches in the code? We may want to keep them seperate. We could also maintain released postgresql documentation -- IE, one set for PostgreSQL 7.4.0, one set for PostgreSQL 7.4.1, etc... These would only have to be built once. -- Jonathan Gardner jgardner@jonathangardner.net
On Wed, 17 Mar 2004, Jonathan Gardner wrote: > I was thinking of writing a cron job to update the CVS tree and then > build the documentation (takes about 10 minutes on my computer). Then I > could push it to wherever you like. Are we currently maintaining two or > three branches in the code? We may want to keep them seperate. if you can write the script, and assuming nobody has objections to it, we can easily run it on the main server, directly into CVS ... doxygen is already installed for one of our other clients ... ---- Marc G. Fournier Hub.Org Networking Services (http://www.hub.org) Email: scrappy@hub.org Yahoo!: yscrappy ICQ: 7615664
On Wednesday 17 March 2004 02:34 am, Neil Conway wrote:
>> Just a heads-up: list.c and pg_list.h will be reimplemented fairly
>> soon in CVS HEAD (the code isn't committed yet, but there's a
>> preliminary patch I can send you if you're interested).
BTW, where are you on that? I'm getting antsy to see it applied.
If it's a matter of finding cycles to get the "big bang" done, maybe
I could help. We could divvy up the backend tree and probably get it
done in a day or so of single-minded hacking.
regards, tom lane
> -----Original Message----- > From: Jonathan Gardner [mailto:jgardner@jonathangardner.net] > Sent: 17 March 2004 18:46 > To: Dave Page > Cc: pgsql-hackers@postgresql.org > Subject: Re: [HACKERS] Doxygen? > > I was thinking of writing a cron job to update the CVS tree > and then build the documentation (takes about 10 minutes on > my computer). Then I could push it to wherever you like. Are > we currently maintaining two or three branches in the code? > We may want to keep them seperate. No problem. We could give you access to the relevant areas to upload via scp. > We could also maintain released postgresql documentation -- > IE, one set for PostgreSQL 7.4.0, one set for PostgreSQL > 7.4.1, etc... These would only have to be built once. Yup :-) Regards, Dave.
> I was thinking of writing a cron job to update the CVS tree and then build > the documentation (takes about 10 minutes on my computer). Then I could > push it to wherever you like. Are we currently maintaining two or three > branches in the code? We may want to keep them seperate. > > We could also maintain released postgresql documentation -- IE, one set for > PostgreSQL 7.4.0, one set for PostgreSQL 7.4.1, etc... These would only > have to be built once. How about posting a 'doxygen commenting guide' to the list so that we know how to comment? Also, maybe it's time we standardised code documentation? :) Chris
-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On Wednesday 17 March 2004 5:54 pm, Christopher Kings-Lynne wrote: > > I was thinking of writing a cron job to update the CVS tree and then > > build the documentation (takes about 10 minutes on my computer). Then > > I could push it to wherever you like. Are we currently maintaining > > two or three branches in the code? We may want to keep them seperate. > > > > We could also maintain released postgresql documentation -- IE, one > > set for PostgreSQL 7.4.0, one set for PostgreSQL 7.4.1, etc... These > > would only have to be built once. > > How about posting a 'doxygen commenting guide' to the list so that we > know how to comment? Also, maybe it's time we standardised code > documentation? :) > Doxygen manuals are available on the 'net at doxygen.sourceforge.com. I'm using the '/' style, so no '@' for me. Read through them at your leisure at http://www.stack.nl/~dimitri/doxygen/manual.html This page in particular sums up all you need to know: http://www.stack.nl/~dimitri/doxygen/docblocks.html As far as a standard, I would like to actually go through and see what works before we talk of that. Personally, I am /stunned/ by the sheer volume of comments in the code, and getting all that to show up in Doxygen is a 6 month project! - -- Jonathan Gardner jgardner@jonathangardner.net -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.2.3 (GNU/Linux) iD8DBQFAWTgpqp6r/MVGlwwRAluNAKCm3zwp5AoY0ChTaJyki/xXRZ+2YACgosV0 RyaDbYFWYIFokmrhjpN4Y+w= =Srgo -----END PGP SIGNATURE-----