On Wed, 27 Jan 2010 21:41:02 +0800 Craig Ringer <cr...@postnewspapers.com.au> wrote:
> I don't code on PostgreSQL's guts, so I'm perhaps not in the best > position to speak, but: > > - Documentation has a cost too, particularly a maintenance cost. > Outdated docs become misleading or downright false and can be much > more harm than good. So a reasonable balance must be struck. I'm > not saying PostgreSQL is _at_ that reasonable balance re its > internal documentation, but there is such a thing as > over-documenting. Writing a small book on each function means you > have to maintain that, and that gets painful if code is undergoing > any sort of major change. I'd be willing to pay for a book. > - It's easy to say "should" when you're not the one writing it. > Personally, I try to say "hey, it's cool that I have access to > this system" and "isn't it great I even have the right to modify > it to do what I want, even though the learning curve _can_ be > pretty steep". Well... I tend to generally make available to others everything I learn. I'd be nice a more advanced use of doxygen so it would be easier to have a map of functions. > Hey, you could contribute yourself - patch some documentation into > those functions where you find that reading the source isn't clear > enough, and they really need a "see also" or "called from" comment > or the like. Right now I've not enough knowledge to hope my notes get into the source code. Once I've a working piece of code I'll put the information I gathered in the process on my web site and if someone find them worth for a better place I'll release them with a suitable license. -- Ivan Sergio Borgonovo http://www.webthatworks.it -- Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-hackers