Add documentation comments to the catalogued SQL functions

components/electric/lib/electric/postgres/extension/functions/create_active_migration.sql.eex

@@ -1,3 +1,8 @@
+-- This function captures the "CREATE TABLE" statement for the table
+-- that's being electrified and stores it in the @ddl_table, in order for it
+-- to be sent over the logical replication stream to Electric and be consumed
+-- by the MigrationConsumer process there.
+
 CREATE OR REPLACE FUNCTION <%= @schema %>.create_active_migration(
     _txid <%= @txid_type %>,
     _txts timestamptz,

components/electric/lib/electric/postgres/extension/functions/electrify.sql.eex

@@ -1,3 +1,13 @@
+-- you can call electrify using one of these variants:
+--
+-- 1. `CALL electric.electrify('my_table')`
+-- 2. `CALL electric.electrify('my_schema', 'my_table')`
+-- 3. `CALL electric.electrify('my_schema.my_table')`
+--
+-- the first two formats also support special characters in the table/schema name:
+--
+-- 4. `CALL electric.electrify('My Schema', 'My Table')`
+
 CREATE OR REPLACE PROCEDURE <%= @schema %>.electrify(
     name1 text,
     name2 text DEFAULT NULL

components/electric/lib/electric/postgres/extension/functions/validate_table_column_defaults.sql.eex

@@ -1,3 +1,6 @@
+-- This function validates each column of the table that's being electrified
+-- and aborts electrification if any column has DEFAULT expression.
+
 CREATE OR REPLACE FUNCTION <%= @schema %>.__validate_table_column_defaults(table_name text)
 RETURNS VOID AS $function$
 DECLARE

components/electric/lib/electric/postgres/extension/functions/validate_table_column_types.sql.eex

@@ -1,3 +1,6 @@
+-- This function validates the type of each column of the table that's being electrified,
+-- to check if the type is supported by Electric.
+
 <%
   valid_column_types =
     ~w[

components/electric/lib/electric/postgres/extension/migrations/20230605141256_electrify_function/electrify.sql.eex

@@ -1,14 +1,4 @@
 -- vim: set shiftwidth=4:tabstop=4
---
--- you can call electrify using one of these variants:
---
--- 1. `CALL electric.electrify('my_table')`
--- 2. `CALL electric.electrify('my_schema', 'my_table')`
--- 3. `CALL electric.electrify('my_schema.my_table')`
---
--- the first two formats also support special characters in the table/schema name:
---
--- 4. `CALL electric.electrify('My Schema', 'My Table')`
 
 CREATE OR REPLACE FUNCTION <%= schema %>.__pg_version() RETURNS integer AS $function$
     SELECT setting::int FROM pg_settings WHERE name = 'server_version_num'