Details
-
Type: Improvement
-
Status: Closed
-
Priority: Major
-
Resolution: Fixed
-
Affects Version/s: 2.1-Beta2
-
Fix Version/s: 3.0
-
Component/s: ACE-Components
-
Labels:None
-
Environment:ICEfaces 3 ACE components
-
Affects:Documentation (User Guide, Ref. Guide, etc.)
Description
The ACE TLD documentation requires a general edit/review pass to improve overall quality and usefulness, and to ensure correctness.
---
Let's make sure that our documentation is truly useful. Some of it leaves a lot to be desired. I'll provide examples in ace:tooltip since I ran across it randomly.
@Property(tlddoc="Boolean value that makes tooltip global, which uses title attributes of elements in page to create the tooltip.", defaultValue="false")
private boolean global;
No idea what this means. Does global place the tooltip directly inside the body? Or it will somehow be used on every element in the page that has a title attribute?
@Property(tlddoc="The mouse event that the tooltip will be displayed (default mouseover)", defaultValue="mouseover")
private String showEvent;
@Property(tlddoc="The mouse event that the tooltip will be closed (default mouseout)", defaultValue="mouseout")
private String hideEvent;
What are all possible values?
@Property(tlddoc="The delay time of the tooltip display in milliseconds (default 140)", defaultValue="140")
private int showDelay;
@Property(tlddoc="The delay time of the tooltip hide in milliseconds (default 0)", defaultValue="0")
private int hideDelay;
@Property(tlddoc="Duration to display the show effect (default 500)", defaultValue="500")
private int showEffectLength;
@Property(tlddoc="Duration to display the hide effect (default 500)", defaultValue="500")
private int hideEffectLength;
The first two explain that the time is in milliseconds but the last two don't.
@Property(name="for", tlddoc="Specifies the id of the component that will display the tooltip")
private String forValue;
@Property(tlddoc="Specifies the id of the element that will display the tooltip")
private String forElement;
I'm not sure what the difference between these is. Is forElement an alternative to for, where I can display the tooltip on an element instead of a component? What is the precedence between the two?
---
Let's make sure that our documentation is truly useful. Some of it leaves a lot to be desired. I'll provide examples in ace:tooltip since I ran across it randomly.
@Property(tlddoc="Boolean value that makes tooltip global, which uses title attributes of elements in page to create the tooltip.", defaultValue="false")
private boolean global;
No idea what this means. Does global place the tooltip directly inside the body? Or it will somehow be used on every element in the page that has a title attribute?
@Property(tlddoc="The mouse event that the tooltip will be displayed (default mouseover)", defaultValue="mouseover")
private String showEvent;
@Property(tlddoc="The mouse event that the tooltip will be closed (default mouseout)", defaultValue="mouseout")
private String hideEvent;
What are all possible values?
@Property(tlddoc="The delay time of the tooltip display in milliseconds (default 140)", defaultValue="140")
private int showDelay;
@Property(tlddoc="The delay time of the tooltip hide in milliseconds (default 0)", defaultValue="0")
private int hideDelay;
@Property(tlddoc="Duration to display the show effect (default 500)", defaultValue="500")
private int showEffectLength;
@Property(tlddoc="Duration to display the hide effect (default 500)", defaultValue="500")
private int hideEffectLength;
The first two explain that the time is in milliseconds but the last two don't.
@Property(name="for", tlddoc="Specifies the id of the component that will display the tooltip")
private String forValue;
@Property(tlddoc="Specifies the id of the element that will display the tooltip")
private String forElement;
I'm not sure what the difference between these is. Is forElement an alternative to for, where I can display the tooltip on an element instead of a component? What is the precedence between the two?
All of our @Component and @Property annotations should have real tlddoc entries specified, but some of them don't. We should get around to that before the release, since we can't do it later like the wiki. I just searched for missing @Component tlddoc, and didn't even try for @Property.
@Component(
tagName = "cellEditor",
componentClass = "org.icefaces.ace.component.celleditor.CellEditor",
generatedClass = "org.icefaces.ace.component.celleditor.CellEditorBase",
rendererClass = "org.icefaces.ace.component.celleditor.CellEditorRenderer",
extendsClass = "javax.faces.component.UIComponentBase",
componentType = "org.icefaces.ace.component.CellEditor",
rendererType = "org.icefaces.ace.component.CellEditorRenderer",
componentFamily = "org.icefaces.ace.CellEditor",
tlddoc = ""
@Component(
tagName = "dataTable",
componentClass = "org.icefaces.ace.component.datatable.DataTable",
generatedClass = "org.icefaces.ace.component.datatable.DataTableBase",
rendererClass = "org.icefaces.ace.component.datatable.DataTableRenderer",
extendsClass = "javax.faces.component.UIData",
componentType = "org.icefaces.ace.component.DataTable",
rendererType = "org.icefaces.ace.component.DataTableRenderer",
componentFamily = "org.icefaces.ace.DataTable",
tlddoc = ""
@Component(
tagName = "expansionToggler",
componentClass = "org.icefaces.ace.component.expansiontoggler.ExpansionToggler",
generatedClass = "org.icefaces.ace.component.expansiontoggler.ExpansionTogglerBase",
rendererClass = "org.icefaces.ace.component.expansiontoggler.ExpansionTogglerRenderer",
extendsClass = "javax.faces.component.UIComponentBase",
componentType = "org.icefaces.ace.component.ExpansionToggler",
rendererType = "org.icefaces.ace.component.ExpansionTogglerRenderer",
componentFamily = "org.icefaces.ace.ExpansionToggler",
tlddoc = ""
@Component(
tagName = "linkButton",
componentClass = "org.icefaces.ace.component.linkbutton.LinkButton",
rendererClass = "org.icefaces.ace.component.linkbutton.LinkButtonRenderer",
generatedClass = "org.icefaces.ace.component.linkbutton.LinkButtonBase",
extendsClass = "javax.faces.component.UICommand",
componentType = "org.icefaces.ace.component.LinkButton",
rendererType = "org.icefaces.ace.component.LinkButtonRenderer",
componentFamily = "org.icefaces.ace.LinkButton"
)
@Component(
tagName = "row",
componentClass = "org.icefaces.ace.component.row.Row",
generatedClass = "org.icefaces.ace.component.row.RowBase",
extendsClass = "javax.faces.component.UIComponentBase",
componentType = "org.icefaces.ace.component.Row",
componentFamily = "org.icefaces.ace.Row",
tlddoc = ""
@Component(
tagName = "rowEditor",
componentClass = "org.icefaces.ace.component.roweditor.RowEditor",
generatedClass = "org.icefaces.ace.component.roweditor.RowEditorBase",
rendererClass = "org.icefaces.ace.component.roweditor.RowEditorRenderer",
extendsClass = "javax.faces.component.UIComponentBase",
componentType = "org.icefaces.ace.component.RowEditor",
rendererType = "org.icefaces.ace.component.RowEditorRenderer",
componentFamily = "org.icefaces.ace.RowEditor",
tlddoc = ""
@Component(
tagName = "rowExpansion",
componentClass = "org.icefaces.ace.component.rowexpander.RowExpander",
generatedClass = "org.icefaces.ace.component.rowexpander.RowExpanderBase",
extendsClass = "javax.faces.component.UIComponentBase",
componentType = "org.icefaces.ace.component.RowExpander",
componentFamily = "org.icefaces.ace.RowExpander",
tlddoc = ""
@Component(
tagName = "panelExpansion",
componentClass = "org.icefaces.ace.component.rowpanelexpander.RowPanelExpander",
generatedClass = "org.icefaces.ace.component.rowpanelexpander.RowPanelExpanderBase",
extendsClass = "javax.faces.component.UIColumn",
componentType = "org.icefaces.ace.component.RowPanelExpander",
componentFamily = "org.icefaces.ace.RowPanelExpander",
tlddoc = ""
@Component(
tagName = "tableConfigPanel",
extendsClass = "javax.faces.component.UIComponentBase",
rendererClass = "org.icefaces.ace.component.tableconfigpanel.TableConfigPanelRenderer",
rendererType = "org.icefaces.ace.component.TableConfigPanelRenderer",
generatedClass = "org.icefaces.ace.component.tableconfigpanel.TableConfigPanelBase",
componentType = "org.icefaces.ace.component.TableConfigPanel",
componentClass = "org.icefaces.ace.component.tableconfigpanel.TableConfigPanel",
componentFamily = "org.icefaces.ace.TableConfigPanel",
tlddoc = "")