Message-ID: <518DFDAC.2060909@fastmail.co.uk>
Date: Sat, 11 May 2013 09:13:32 +0100
From: Sian Mountbatten <poenikatu@fastmail.co.uk>
User-Agent: Mozilla/5.0 (X11; Linux i686;
	rv:17.0) Gecko/20130328 Thunderbird/17.0.5
MIME-Version: 1.0
To: Erwin Brandstetter <brandstetter@falter.at>,
 pgsql-docs@postgresql.org
Subject: Re: Reference function arguments by name
References: <518C0B2B.9040909@falter.at>
In-Reply-To: <518C0B2B.9040909@falter.at>
Content-Type: multipart/alternative;
	boundary="------------050206000608010700090407"
Precedence: bulk
Sender: pgsql-docs-owner@postgresql.org

This is a multi-part message in MIME format.
--------------050206000608010700090407
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit

On 2013-05-09 21:46, Erwin Brandstetter wrote:
> Hi!
>
> The manual says here:
> http://www.postgresql.org/docs/current/interactive/sql-createfunction.html
> http://www.postgresql.org/docs/devel/static/sql-createfunction.html
>
>> argname
>>
>>     The name of an argument. Some languages (currently only PL/pgSQL)
>>     let you use the name in the function body. For other languages
>>     the name of an input argument is just extra documentation, so far
>>     as the function itself is concerned; but you can use input
>>     argument names when calling a function to improve readability
>>     (see Section 4.3
>>     <http://www.postgresql.org/docs/current/interactive/sql-syntax-calling-funcs.html>).
>>     In any case, the name of an output argument is significant,
>>     because it defines the column name in the result row type. (If
>>     you omit the name for an output argument, the system will choose
>>     a default column name.)
>>
>
> This has changed in version 9.2. SQL functions can reference the name. 
> Ergo:
>
> s /(currently only PL/pgSQL) / (currently only PL/pgSQL and SQL)
>
>
> I tested it and it's /correctly /documented here:
> http://www.postgresql.org/docs/current/interactive/xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS
>
> > Arguments of a SQL function can be referenced in the function body 
> using either names or numbers.
>
>
> Regards
> Erwin
It looks strongly that you people are of the opinion that "the code 
documents
itself". That is a myth produced by lazy software developers who cannot 
document
their code properly. You ought to be using Cweb for C code. Have a look at
the code for SQLite to see how comments in C can be used to provide decent
documentation

Fortunately, I do not use C. I prefer a HIGH-level language :-)

-- 
Sian Mountbatten
Algol 68 Specialist


--------------050206000608010700090407
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: 7bit

<html>
  <head>
    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type">
  </head>
  <body bgcolor="#FFFFFF" text="#000000">
    <div class="moz-cite-prefix">On 2013-05-09 21:46, Erwin Brandstetter
      wrote:<br>
    </div>
    <blockquote cite="mid:518C0B2B.9040909@falter.at" type="cite">
      <meta http-equiv="content-type" content="text/html; charset=UTF-8">
      <tt>Hi!<br>
        <br>
        The manual says here:<br>
        <a moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://www.postgresql.org/docs/current/interactive/sql-createfunction.html">http://www.postgresql.org/docs/current/interactive/sql-createfunction.html</a><br>
        <a moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://www.postgresql.org/docs/devel/static/sql-createfunction.html">http://www.postgresql.org/docs/devel/static/sql-createfunction.html</a><br>
        <br>
      </tt>
      <blockquote type="cite">
        <dl>
          <dt><tt class="REPLACEABLE c2">argname</tt></dt>
          <dd>
            <p>The name of an argument. Some languages (currently only
              PL/pgSQL) let you use the name in the function body. For
              other languages the name of an input argument is just
              extra documentation, so far as the function itself is
              concerned; but you can use input argument names when
              calling a function to improve readability (see <a
                moz-do-not-send="true"
href="http://www.postgresql.org/docs/current/interactive/sql-syntax-calling-funcs.html">Section

                4.3</a>). In any case, the name of an output argument is
              significant, because it defines the column name in the
              result row type. (If you omit the name for an output
              argument, the system will choose a default column name.)</p>
          </dd>
        </dl>
      </blockquote>
      <br>
      <tt>This has changed in version 9.2. SQL functions can reference
        the name. </tt><tt><tt>Ergo:<br>
        </tt><br>
        <tt><tt>s /(currently only PL/pgSQL) / </tt></tt><tt><tt>(currently

            only PL/pgSQL and SQL)<br>
            <br>
            <br>
          </tt></tt>I tested it and it's <i>correctly </i>documented
        here:<br>
        <a moz-do-not-send="true" class="moz-txt-link-freetext"
href="http://www.postgresql.org/docs/current/interactive/xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS">http://www.postgresql.org/docs/current/interactive/xfunc-sql.html#XFUNC-SQL-FUNCTION-ARGUMENTS</a><br>
        <br>
      </tt><tt>&gt; </tt><tt>Arguments of a SQL function can be
        referenced in the function body using either names or numbers.<br>
        <br>
      </tt><tt><tt><br>
          Regards<br>
          Erwin<br>
        </tt></tt> </blockquote>
    <font face="DejaVu Sans Mono">It looks strongly that you people are
      of the opinion that "the code documents<br>
      itself". That is a myth produced by lazy software developers who
      cannot document<br>
      their code properly. You ought to be using Cweb for C code. Have a
      look at<br>
      the code for SQLite to see how comments in C can be used to
      provide decent<br>
      documentation<br>
      <br>
      Fortunately, I do not use C. I prefer a HIGH-level language :-)<br>
    </font><br>
    <pre class="moz-signature" cols="72">-- 
Sian Mountbatten
Algol 68 Specialist


</pre>
  </body>
</html>

--------------050206000608010700090407--