Bug 493657 - Extension points not appearing in Help
Improve documentation for .elementProvider and .propertyHandler
Change-Id: Iae9058932398234614f12a7fdca9c8b549725ecb
diff --git a/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.elementProvider.exsd b/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.elementProvider.exsd
index 89f40d8..9587828 100644
--- a/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.elementProvider.exsd
+++ b/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.elementProvider.exsd
@@ -3,10 +3,13 @@
<schema targetNamespace="org.eclipse.e4.ui.css.core" xmlns="http://www.w3.org/2001/XMLSchema">
<annotation>
<appinfo>
- <meta.schema plugin="org.eclipse.e4.ui.css.core" id="org.eclipse.e4.ui.css.core.elementProvider" name="element_provider"/>
+ <meta.schema plugin="org.eclipse.e4.ui.css.core" id="org.eclipse.e4.ui.css.core.elementProvider" name="DOM Element Provider"/>
</appinfo>
<documentation>
- Maps widgets or objects to an element provider.
+ <p>
+The <code>org.eclipse.e4.ui.css.core.elementProvider</code> extension point is used to map widgets or objects to elements of a <em>Document Object Model</em> (DOM). The Element Provider is responsible for checking whether the supplied widgets/objects are compatible with the provided CSS Engine.
+</p>
+
</documentation>
</annotation>
@@ -48,6 +51,11 @@
</element>
<element name="provider">
+ <annotation>
+ <documentation>
+ An object that maps widgets/objects to DOM elements.
+ </documentation>
+ </annotation>
<complexType>
<sequence>
<element ref="widget" minOccurs="1" maxOccurs="unbounded"/>
@@ -55,7 +63,7 @@
<attribute name="class" type="string">
<annotation>
<documentation>
-
+ the implementation class for the element provider. This class must implement the <samp>org.eclipse.e4.ui.css.core.dom.IElementProvider</samp> interface.
</documentation>
<appinfo>
<meta.attribute kind="java" basedOn=":org.eclipse.e4.ui.css.core.dom.IElementProvider"/>
@@ -66,11 +74,16 @@
</element>
<element name="widget">
+ <annotation>
+ <documentation>
+ A type of widget/object that this provider can map to a DOM element.
+ </documentation>
+ </annotation>
<complexType>
- <attribute name="class" type="string">
+ <attribute name="class" type="string" use="required">
<annotation>
<documentation>
-
+ the type of a widget/object supported by this element provider. This type may be either a class or interface.
</documentation>
<appinfo>
<meta.attribute kind="java"/>
@@ -85,7 +98,7 @@
<meta.section type="since"/>
</appinfo>
<documentation>
- [Enter the first release in which this extension point appears.]
+ 0.9
</documentation>
</annotation>
@@ -94,7 +107,13 @@
<meta.section type="examples"/>
</appinfo>
<documentation>
- [Enter extension point usage example here.]
+ <pre>
+ <extension point="org.eclipse.e4.ui.css.core.elementProvider">
+ <provider class="org.eclipse.e4.ui.css.swt.dom.SWTElementProvider">
+ <widget class="org.eclipse.swt.widgets.Control"/>
+ </provider>
+ </extension>
+</pre>
</documentation>
</annotation>
@@ -103,7 +122,10 @@
<meta.section type="apiinfo"/>
</appinfo>
<documentation>
- [Enter API information here.]
+ <tt>elementProvider</tt> is currently internal and should not be considered API.
+<p>
+The supplied element provider must implement the <samp>org.eclipse.e4.ui.css.core.dom.IElementProvider<samp> interface.
+</p>
</documentation>
</annotation>
@@ -112,7 +134,7 @@
<meta.section type="implementation"/>
</appinfo>
<documentation>
- [Enter information about supplied implementation of this extension point.]
+ None.
</documentation>
</annotation>
diff --git a/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.propertyHandler.exsd b/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.propertyHandler.exsd
index 3c58df6..a0788ea 100644
--- a/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.propertyHandler.exsd
+++ b/bundles/org.eclipse.e4.ui.css.core/schema/org.eclipse.e4.ui.css.core.propertyHandler.exsd
@@ -77,7 +77,7 @@
<attribute name="handler" type="string">
<annotation>
<documentation>
- This class implements the property setting.
+ implements the property fetching and setting. This class must implement <samp>org.eclipse.e4.ui.css.core.dom.properties.ICSSPropertyHandler</samp>.
</documentation>
<appinfo>
<meta.attribute kind="java" basedOn=":org.eclipse.e4.ui.css.core.dom.properties.ICSSPropertyHandler"/>
@@ -92,7 +92,7 @@
<attribute name="name" type="string" use="required">
<annotation>
<documentation>
- The CSS property name. If not officially part of the W3C's <a href="http://www.w3.org/TR/CSS2/">CSS 2 Standard</a> then the property should be prefixed. For example, SWT-specific properties are prefixed with <tt>-swt-</tt>.
+ The CSS property name. If not officially part of the W3C's <a href="http://www.w3.org/TR/CSS2/">CSS 2 Standard</a> then the property should be prefixed. For example, SWT-specific properties are prefixed with <tt>swt-</tt> . (Due to a bug in the underlying implementation, we cannot use a leading hyphen as specified in the standard, "-swt-".)
</documentation>
</annotation>
</attribute>
@@ -106,6 +106,14 @@
</complexType>
</element>
+ <annotation>
+ <appinfo>
+ <meta.section type="since"/>
+ </appinfo>
+ <documentation>
+ 0.9
+ </documentation>
+ </annotation>
<annotation>
<appinfo>
@@ -125,6 +133,20 @@
</documentation>
</annotation>
+ <annotation>
+ <appinfo>
+ <meta.section type="apiinfo"/>
+ </appinfo>
+ <documentation>
+ <tt>propertyHandler</tt> is currently internal and should not be considered API.
+<p>
+The property handler <em>provider</em> must implement the <samp>org.eclipse.e4.ui.css.core.dom.properties.ICSSPropertyHandlerProvider</samp> interface. In addition to providing property handlers, the provider is also expected to provide the default style declaration for an element.
+</p>
+<p>
+Property handlers must implement the <samp>org.eclipse.e4.ui.css.core.dom.properties.ICSSPropertyHandler<samp> interface; there are several specializations to allow providing additional functionality. There are a number of specialized interfaces, abstract classes, and helper classes, for implementing property handlers. There is also some support for defining composite CSS2 properties, such as <em>background</em>, defined in <samp>org.eclipse.e4.ui.css.core.dom.properties.css2</samp>.
+</p>
+ </documentation>
+ </annotation>
<annotation>
<appinfo>
diff --git a/bundles/org.eclipse.e4.ui.css.core/src/org/eclipse/e4/ui/css/core/dom/IElementProvider.java b/bundles/org.eclipse.e4.ui.css.core/src/org/eclipse/e4/ui/css/core/dom/IElementProvider.java
index 6a5a50d..4d443b0 100644
--- a/bundles/org.eclipse.e4.ui.css.core/src/org/eclipse/e4/ui/css/core/dom/IElementProvider.java
+++ b/bundles/org.eclipse.e4.ui.css.core/src/org/eclipse/e4/ui/css/core/dom/IElementProvider.java
@@ -20,9 +20,11 @@
public interface IElementProvider {
/**
- * Return the w3c Element which wrap the native widget <code>element</code>
- * (SWT Control, Swing JComponent). The <code>element</code> can be the
- * w3c Element.
+ * Return the w3c {@link Element} which wrap the native widget
+ * <code>element</code> (SWT Control, Swing JComponent). The
+ * <code>element</code> can be the w3c Element. The provider should check
+ * that the supplied widgets/objects are compatible with the provided CSS
+ * Engine.
*
* @param element
* @param engine
