Doxygen?

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, Pennsylvania 19073

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