mention the trigger purpose

diff --git a/sql/pgq/triggers/pgq_triggers.sql.in b/sql/pgq/triggers/pgq_triggers.sql.in
index 2de9543c7e64c64e32a66260b91f2c63137d1c5a..d3e0d978671c32fabff2aa7446e1027c8f70dd12 100644 (file)
--- a/sql/pgq/triggers/pgq_triggers.sql.in
+++ b/sql/pgq/triggers/pgq_triggers.sql.in
@@ -6,6 +6,11 @@
 --      queue.  It does not auto-detect table structure, it needs to be passed
 --      as trigger arg.
 --
+-- Purpose:
+--      Used by Londiste to generate replication events.  The "partial SQL"
+--      format is more compact than the urlencoded format but cannot be
+--      parsed, only applied.  Which is fine for Londiste.
+--
 -- Parameters:
 --      arg1 - queue name
 --      arg2 - column type spec string where each column corresponds to one char (k/v/i).
@@ -31,9 +36,13 @@ AS 'MODULE_PATHNAME', 'pgq_logtriga' LANGUAGE C;
 --      Automatic SQL trigger.  It puts row data in partial SQL form into
 --      queue.  It autodetects table structure.
 --
+-- Purpose:
+--      Written as more flexible version of logtriga to handle exceptional cases
+--      where there is no primary key index on table etc.
+--
 -- Parameters:
---    arg1 - queue name
---    argX - any number of optional arg, in any order
+--      arg1 - queue name
+--      argX - any number of optional arg, in any order
 --
 -- Optinal arguments:
 --      SKIP                - The actual operation should be skipped
@@ -54,6 +63,11 @@ AS 'MODULE_PATHNAME', 'pgq_sqltriga' LANGUAGE C;
 --
 --      Trigger function that puts row data in urlencoded form into queue.
 --
+-- Purpose:
+--     Used as producer for several PgQ standard consumers (cube_dispatcher, 
+--      queue_mover, table_dispatcher).  Basically for cases where the
+--      consumer wants to parse the event and look at the actual column values.
+--
 -- Trigger parameters:
 --      arg1 - queue name
 --      argX - any number of optional arg, in any order
@@ -69,11 +83,11 @@ AS 'MODULE_PATHNAME', 'pgq_sqltriga' LANGUAGE C;
 --      ev_extra1    - table name
 --
 -- Regular listen trigger example:
--- >  CREATE TRIGGER triga_nimi AFTER INSERT OR UPDATE ON customer
--- >  FOR EACH ROW EXECUTE PROCEDURE pgq.logutriga('qname');
+-- >   CREATE TRIGGER triga_nimi AFTER INSERT OR UPDATE ON customer
+-- >   FOR EACH ROW EXECUTE PROCEDURE pgq.logutriga('qname');
 --
 -- Redirect trigger example:
--- >   CREATE TRIGGER triga_nimi AFTER INSERT OR UPDATE ON customer
+-- >   CREATE TRIGGER triga_nimi BEFORE INSERT OR UPDATE ON customer
 -- >   FOR EACH ROW EXECUTE PROCEDURE pgq.logutriga('qname', 'SKIP');
 -- ----------------------------------------------------------------------
 CREATE OR REPLACE FUNCTION pgq.logutriga() RETURNS TRIGGER