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(at)jonathangardner(dot)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(at)candle(dot)pha(dot)pa(dot)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(at)jonathangardner(dot)net
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.3 (GNU/Linux)

iD8DBQFAV/Upqp6r/MVGlwwRAjssAKCl7GaW36qTH5svMlQronc+FzhMYQCeOcwv
Vi7AmyIS/pjYUong60sYxfE=
=WSfP
-----END PGP SIGNATURE-----

Folks, this is what greenhorns like me have been waiting for. Great stuff.

Keep the faith

Zoltan

----- Original Message -----
From: "Jonathan M. Gardner" <jgardner(at)jonathangardner(dot)net>
To: "Bruce Momjian" <pgman(at)candle(dot)pha(dot)pa(dot)us>
Cc: <pgsql-hackers(at)postgresql(dot)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(at)jonathangardner(dot)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(at)jonathangardner(dot)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(at)jonathangardner(dot)net

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