Re: documentation structure

Corey Huinker <corey.huinker@gmail.com> writes:

>>
>> I havent dealt with variadic yet, since the two styles are visually
>> different, not just markup (<optional>...</optional> renders as [...]).
>>
>> The two styles for variadic are the what I call caller-style:
>>
>>    concat ( val1 "any" [, val2 "any" [, ...] ] )
>>    format(formatstr text [, formatarg "any" [, ...] ])
>>
>
> While this style is obviously clumsier for us to compose, it does avoid
> relying on the user understanding what the word variadic means. Searching
> through online documentation of the python *args parameter, the word
> variadic never comes up, the closest they get is "variable length
> argument". I realize that python is not SQL, but I think it's a good point
> of reference for what concepts the average reader is likely to know.

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>


> Looking at the patch, I think it is good, though I'd consider doing some
> indentation for the nested <optional>s to allow the author to do more
> visual tag-matching. The ']'s were sufficiently visually distinct that we
> didn't really need or want nesting, but <optional> is just another tag to
> my eyes in a sea of tags.

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>

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.

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>


I'm not quite sure what to with things like json_object which have even
more complex nexting of optional parameters, but I do think the current
200+ character lines are too long.

- ilmari