I suggested this in IRC and they recommended sending it to this
mailing list, at
https://www.postgresql.org/docs/9.6/static/plpgsql-structure.html when
introducing plpgsql functions the double dollar quote is used and
assumes the user is familiar with it. In my experience people may
happen across this while still being unfamiliar with this syntax and
be further confused as they go through the plpgsql section.
My suggestion is to add in a mention that using the double dollar
syntax is typical for function body declarations and provide a link to
the https://www.postgresql.org/docs/9.6/static/sql-syntax-lexical.html#SQL-SYNTAX-DOLLAR-QUOTING
section similar to what is provided in the
https://www.postgresql.org/docs/9.6/static/sql-createfunction.html
'definition' section.
Something like a new TIP or NOTE box with (text mostly taken from the
sql-createfunction section):
Because the function definition is a string literal, it is often
helpful to use dollar quoting (see Section 4.1.2.4), rather than the
normal single quote syntax. Without dollar quoting, any single quotes
or backslashes in the function definition must be escaped by doubling
them.
--Kurt Kartaltepe