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

Tue, 16 Mar 2004 17:40:54 -0800
Jonathan Gardner <jgardner@jonathangardner.net>
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

Tue, 16 Mar 2004 20:56:16 -0500 (EST)
Bruce Momjian <pgman@candle.pha.pa.us>
Re: 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-----

Tue, 16 Mar 2004 22:50:17 -0800
"Jonathan M. Gardner" <jgardner@jonathangardner.net>
Re: Doxygen?
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




Wed, 17 Mar 2004 15:01:21 +0100
"BARTKO, Zoltan" <bartko.zoltan@pobox.sk>
Re: Doxygen?
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

Wed, 17 Mar 2004 10:42:03 -0800
Jonathan Gardner <jgardner@jonathangardner.net>
Re: Doxygen?
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

Wed, 17 Mar 2004 16:00:34 -0500
Tom Lane <tgl@sss.pgh.pa.us>
list.c (was Re: Doxygen?)