Code documentation

On Thu, 2004-12-02 at 10:58 +0100, Gevik Babakhani wrote:

I was wondering if there are any interests or plans for documenting
various functions in the code which currently are not documented.

I don't know of any systematic effort to do this. I try to document
undocumented code as necessary while making related changes, and I would
imagine other developers do the same.

I would like to start this discussion to see if we want to do this.

It sounds like a good idea to me. Feel free to submit documentation
patches to the -patches list.

Another area where we could stand to do better is in higher-level
documentation of how the internals of the system work. For example,
something like the Postgres95 Implementation Guide:

http://pluto.iis.nsk.su/postgres95/impl-guide/

but more complete, and up-to-date. There is some documentation in this
vein (such as the README files for specific subsystems), but IMHO we
could do with more.

-Neil

I think the basis in understanding how PostgreSQL works depends
on the documentation to certain extend and the level of one's programming
and database knowledge of course.

At this moment I am gathering information from anywhere I can get a hold
of regarding PostgresSQL.

I have requested a repository at pgFoundry called "Postgres Knowledge Base"
I am planning to gather/write FAQ,HOW TO and KB articles.

About the higher-level documentation of how the internals, it would be great

if anyone could send me links, white papers, whatever documentation you
think it is
important.

I also would like to know if anyone would be interested to have an online
browsable version
of source code? This can easily be done by doxygen to some acceptable level.

Regards,
Gevik.

-----Original Message-----
From: Neil Conway [mailto:neilc@samurai.com]
Sent: Friday, December 03, 2004 2:19 AM
To: Gevik Babakhani
Cc: pgsql-hackers
Subject: Re: [HACKERS] Code documentation

On Thu, 2004-12-02 at 10:58 +0100, Gevik Babakhani wrote:

I was wondering if there are any interests or plans for documenting
various functions in the code which currently are not documented.

I don't know of any systematic effort to do this. I try to document
undocumented code as necessary while making related changes, and I would
imagine other developers do the same.

I would like to start this discussion to see if we want to do this.

It sounds like a good idea to me. Feel free to submit documentation patches
to the -patches list.

Another area where we could stand to do better is in higher-level
documentation of how the internals of the system work. For example,
something like the Postgres95 Implementation Guide:

http://pluto.iis.nsk.su/postgres95/impl-guide/

but more complete, and up-to-date. There is some documentation in this vein
(such as the README files for specific subsystems), but IMHO we could do
with more.

-Neil

Great. Documentation of the source code helps many developers become
more productive.

---------------------------------------------------------------------------

Gevik Babakhani wrote:

I think the basis in understanding how PostgreSQL works depends
on the documentation to certain extend and the level of one's programming
and database knowledge of course.

At this moment I am gathering information from anywhere I can get a hold
of regarding PostgresSQL.

I have requested a repository at pgFoundry called "Postgres Knowledge Base"
I am planning to gather/write FAQ,HOW TO and KB articles.

About the higher-level documentation of how the internals, it would be great

if anyone could send me links, white papers, whatever documentation you
think it is
important.

I also would like to know if anyone would be interested to have an online
browsable version
of source code? This can easily be done by doxygen to some acceptable level.

Regards,
Gevik.

-----Original Message-----
From: Neil Conway [mailto:neilc@samurai.com]
Sent: Friday, December 03, 2004 2:19 AM
To: Gevik Babakhani
Cc: pgsql-hackers
Subject: Re: [HACKERS] Code documentation

On Thu, 2004-12-02 at 10:58 +0100, Gevik Babakhani wrote:

I was wondering if there are any interests or plans for documenting
various functions in the code which currently are not documented.

I don't know of any systematic effort to do this. I try to document
undocumented code as necessary while making related changes, and I would
imagine other developers do the same.

I would like to start this discussion to see if we want to do this.

It sounds like a good idea to me. Feel free to submit documentation patches
to the -patches list.

Another area where we could stand to do better is in higher-level
documentation of how the internals of the system work. For example,
something like the Postgres95 Implementation Guide:

http://pluto.iis.nsk.su/postgres95/impl-guide/

but more complete, and up-to-date. There is some documentation in this vein
(such as the README files for specific subsystems), but IMHO we could do
with more.

-Neil

---------------------------(end of broadcast)---------------------------
TIP 9: the planner will ignore your desire to choose an index scan if your
joining column's datatypes do not match

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