Re: comments in argument list of plpgsql get stripped?

-----Original Message-----
From: pgsql-general-owner@postgresql.org
[mailto:pgsql-general-owner@postgresql.org] On Behalf Of Ralph Graulich
Sent: Friday, January 20, 2012 12:28 PM
To: pgsql-general@postgresql.org
Subject: [GENERAL] comments in argument list of plpgsql get stripped?

Hi,

How can I store inline comments in the argument list of a plpgsql function
to document complex overloaded functions with lots of arguments? It seems
that PostgreSQL accepts the comments, but strips them as the function gets
stored.

I am using PostgreSQL 9.1.2.

+++
CREATE FUNCTION func_test(
    -- comment for argument 1
    -- quite longish, explaining the details
    argument1 TEXT
    -- comment for argument 2
    -- even more information
    , argument2 TEXT
)
RETURNS smallint AS
$BODY$
BEGIN
-- this comment gets stored correctly
RETURN 1;
END;
$BODY$
LANGUAGE plpgsql IMMUTABLE
COST 100;
+++

According to the server log file PostgreSQL gets sent all the comments
correctly, so it is not the client that already strips the comments.

+++
[...]
statement: CREATE FUNCTION func_test(
        -- comment for argument 1
        -- quite longish, explaining the details
        argument1 TEXT
        -- comment for argument 2
        -- even more information
        , argument2 TEXT
    )
    RETURNS smallint AS
    $BODY$
    BEGIN
    -- this comment gets stored correctly
    RETURN 1;
    END;
    $BODY$
    LANGUAGE plpgsql IMMUTABLE
    COST 100;
+++


select func_test('foo', 'bar');
 func_test
-----------
         1
(1 row)


Best regards,
   Ralph

------------------------------------------------------------------

Ralph,

The fact that you can write comments in the middle of the arguments in an
artifact of the parser and likely there is not reasonable way to get them to
persist.  You either want to use "COMMENT ON" like Raymond said or you can
simply move the comments into the body of the function.  The relevant table
that stores the function stores everything except the body as individual
fields so that it can facilitate dependency tracking and type verification,
etc...  In order to do this the input needs to be stripped of all comments
and newlines/control-characters so that only syntactically meaningful
content remains.

The fundamental issue is that the input arguments to a function are stored
as an array on pg_proc and thus to do not have their own OID with which to
link onto pg_description.

The fundamental question is by what means do you expect to be able to view
and/or modify these comments?

Feel free to provide thoughts and suggestions regarding how core could be
modified to fit your intended use-case but I would offer that unless you are
willing to fund and/or do the work that it isn't going to get much attention
due apparent need to modify the catalogs and introduce a total new way of
dealing with comments.  It is not the current policy of PostgreSQL to
capture and store original DDL but instead it parsers the DDL into the
needed catalog entries and then recombines the entries into a "normalized"
form when necessary (e.g., for pg_dump).

David J.