Обсуждение: Code documentation
Dear People, I was wondering if there are any interests or plans for documenting various functions in the code which currently are not documented. I would like to start this discussion to see if we want to do this. If I am the first one with this suggestion (I can't imagine) then I am very interested considering the options and future plans. Regards, Gevik
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, Pennsylvania19073