Re: documentation structure

>
> Yeah, we can't expect everyone wanting to call a built-in function to
> know how they would define an equivalent one themselves. In that case I
> propos marking it up like this:
>
> <function>format</function> (
> <parameter>formatstr</parameter> <type>text</type>
> <optional>, <parameter>formatarg</parameter> <type>"any"</type>
> <optional>, ...</optional> </optional> )
> <returnvalue>text</returnvalue>
>

Looks good, but I guess I have to ask: is there a parameter-list tag out
there instead of (, and should we be using that?

> The requisite nesting when there are multiple optional parameters makes
> it annoying to wrap and indent it "properly" per XML convention, but how
> about something like this, with each parameter on a line of its own, and
> all the closing </optional> tags on one line?
>
> <function>regexp_substr</function> (
> <parameter>string</parameter> <type>text</type>,
> <parameter>pattern</parameter> <type>text</type>
> <optional>, <parameter>start</parameter> <type>integer</type>
> <optional>, <parameter>N</parameter> <type>integer</type>
> <optional>, <parameter>flags</parameter> <type>text</type>
> <optional>, <parameter>subexpr</parameter> <type>integer</type>
> </optional> </optional> </optional> </optional> )
> <returnvalue>text</returnvalue>
>

Yes, that has an easy count-the-vertical, count-the-horizontal,
do-they-match flow to it.

> A lot of functions mostly follow this style, except they tend to put the
> first parameter on the same line of the function namee, even when that
> makes the line overly long. I propose going the other way, with each
> parameter on a line of its own, even if the first one would fit after
> the function name, except the whole parameter list fits after the
> function name.
>

+1

>
> Also, when there's only one optional argument, or they're independently
> optional, not nested, the </optional> tag should go on the same line as
> the parameter.
>
> <function>substring</function> (
> <parameter>bits</parameter> <type>bit</type>
> <optional> <literal>FROM</literal> <parameter>start</parameter>
> <type>integer</type> </optional>
> <optional> <literal>FOR</literal> <parameter>count</parameter>
> <type>integer</type> </optional> )
> <returnvalue>bit</returnvalue>
>

+1