> > 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
