[oXygen-user] Functions signatures in XSLT documentation

[Florent Georges]

Radu Coravu wrote:

  Hi,

> When documentation is generated from an XSLT 2.0 we are
> thinking to make the link to a function more compact by
> removing the type of its parameters:

> f:function-name($param as xs:string) -->
> f:function-name($param)

  I think that's a very good idea ;-)  Personally, I'd also
change the following:

  1) I'd rather use f:function-name#1, that is, the function name
     and its arity, which is the syntax to identify a function in
     XPath 3.0 (thus in XSLT and XQuery 3.0 as well); if you have
     3 or 4 parameters with meaningful names, that is likely to
     obfuscate what should really be a concise and clear list.

     That can maybe be an option in the documentation generation
     dialog box (function item syntax, short signature form, or
     complete signature form with types).  Specifying the arity
     in the menu for non-overloaded functions (function names
     with a single one arity) is not necessary and could be
     dropped (or be an option too).

  2) I'd add the complete signature (param names and types, and
     return type) in a tooltip box displayed on a mouseover (for
     media supporting it).

  PS: The name of the section for a function is "Function f:test"
even if the function is overloaded, in which case we have several
sections named the same way, without the arity.

  PPS: With oXygen 12.2 on Mac OS X, when I generate the doc of a
stylesheet, the menu is not anymore on the left-hand side, but on
top of the file instead (see enclosed screenshot).

  Regards,

-- 
Florent Georges
http://fgeorges.org/

-------------- next part --------------
A non-text attachment was scrubbed...
Name: xslt-doc-menu-on-top.png
Type: image/png
Size: 48043 bytes
Desc: not available
Url : http://www.oxygenxml.com/pipermail/oxygen-user/attachments/20110531/50a6ab6c/attachment.png