PGCOMMENT(1)

NAME
pgcomment - extract javadoc style comments from DDL SQL file and generate appropriate "COMMENT ON" commands.

SYNOPSIS
pgcomment [--html|--latex] < ddl.sql > outputfile

OPTIONS

--html
    generate a stub html file.

--latex
    generate a stub LaTeX file.

ENVIRONMENT

LATEX_SEC
    define the LaTeX section/chapter type. Defaults to "section".

HTML_SEC
    define the HTML headline type. Defaults to "H2".

DESCRIPTION
pgcomment excepts a SQL text on STDIN which should contain DDL command along with specially formatted comments. Those comments are written as "COMMENT ON" commands to STDOUT. You can then execute the created SQL commands in PostgreSQL to have object descriptions (comments) available inside the database.

In this pre-release version the comments in the DDL SQL have to start with the /** start and end with */. The object "CREATE" statement which the comment describes must immediately follow the comment. After the comment start characters you must indicate the comment/SQL object type by repeating the object type of the CREATE statement (this requirement will be dropped in future releases of pgcomment). Like SQL pgcomment is case-insensitive when recognizing keywords.

The "TABLE" object type is special, since it can contain comments for the columns. These have to be preceded by a "@column" tag and the column comment must be separated by newlines.

EXAMPLE
The following input SQL DDL are the contents of the file example.sql:

 /** table example
   The table "example" shows how to set the column comments in a table.

   @column nr the primary key as artifical autoassigned integer

   @column name a person's name

   @column job a person's job description
 */
 create table example (
   nr   serial,
   name text not null unique,
   job  text not null
 );

 /** FUNCTION normalize_name(name text)
 normalizes "name".  Only lowercase characters, digits, dash and underscore survive the normalization.
 @param name an arbitrary string.
 @return name parameter normalized.
 */
 CREATE OR REPLACE FUNCTION normalize_name(name text)
 RETURNS TEXT
 AS $$
 BEGIN
   RETURN regexp_replace(lower(name), E'[^\\w\\d\\-_]', '', 'g');
 END;
 $$ LANGUAGE plpgsql IMMUTABLE STRICT;

An execution of pgcomment will produce the following output:

 COMMENT ON COLUMN example.nr IS 'the primary key as artifical autoassigned integer';
 COMMENT ON COLUMN example.name IS 'a person''s name';
 COMMENT ON COLUMN example.job IS 'a person''s job description';
 COMMENT ON TABLE example IS 'The table "example" shows how to set the column comments in a table.';
 COMMENT ON FUNCTION normalize_name(name text) IS 'normalizes "name".  Only lowercase characters, digits, dash and underscore survive the normalization.
 @param name an arbitrary string.
 @return name parameter normalized.';

(Note that there is currently no support for the javadoc style function parameter and return value description.)

SEE ALSO
<http://www.postgresql.org/docs/8.3/interactive/sql-commands.html>

AUTHOR
Dirk Jagdmann <doj@cubic.org> <http://pgfoundry.org/projects/pg-toolbox/>

LICENSE
zlib/libpng license: <http://en.wikipedia.org/wiki/Zlib_License>