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:
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?
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.