Message-ID: <47CDB9D2.5070106@denterprises.org>
Date: Tue, 04 Mar 2008 16:06:26 -0500
From: Colin Wetherbee <cww@denterprises.org>
User-Agent: Thunderbird 2.0.0.12 (Windows/20080213)
MIME-Version: 1.0
To: Shahaf Abileah <shahaf@redfin.com>
CC: pgsql-general@postgresql.org
Subject: Re: Documenting a DB schema
References: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan>
In-Reply-To: <082D8A131DF72A4D88C908A1AD3DEB22023B34F2@mail-1.rf.lan>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit

Shahaf Abileah wrote:
> It would be great if the documentation could be kept as close to the 
> code as possible – that way we stand a chance of keeping it up to date.  
> So, in the same way that Java docs go right there on top of the class or 
> method definitions, it would be great if I could attach my comments to 
> the table definitions. It looks like MySQL has that kind of capability:

Please do not cross-post.  One list is enough.

PostgreSQL has that functionality, too.

cww=# CREATE TABLE foo (a INTEGER, b INTEGER);
CREATE TABLE
cww=# COMMENT ON TABLE foo IS 'my comment';
COMMENT
cww=# \d+
               List of relations
  Schema | Name | Type  | Owner | Description
--------+------+-------+-------+-------------
  public | foo  | table | cww   | my comment
(1 row)

COMMENT is well-documented.

http://www.postgresql.org/docs/8.3/static/sql-comment.html

Colin