Re: [oXygen-user] Functions signatures in XSLT documentation
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/
Hi Florent, The feedback to minimize the function signature originated from you, thanks for the additional suggestions. About this question:
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).
When generating XSLT documentation there is a checkbox called "Split output into multiple files". If it is unchecked then the behavior is to show the entire output in a single file thus removing the frameset and showing the navigation menu on top. Regards, Radu Radu Coravu <oXygen/> XML Editor, Schema Editor and XSLT Editor/Debugger http://www.oxygenxml.com On 5/31/2011 2:44 PM, Florent Georges wrote:
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,
Radu Coravu wrote:
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).
When generating XSLT documentation there is a checkbox called "Split output into multiple files". If it is unchecked then the behavior is to show the entire output in a single file thus removing the frameset and showing the navigation menu on top.
Oh right, because the left-hand-side menu uses frames. Ok, makes sense, I haven't thought about the implication of that option on the menu. Thanks for listening to suggestions! Regards, -- Florent Georges http://fgeorges.org/
participants (2)
-
Florent Georges -
Radu Coravu