424986 EP Document tools.emf.ui.editors.contributionClassCreator

Change-Id: Iaf1e7e5ece0984b6decbed81cfb0ff1dc465ea64
Signed-off-by: Marco Descher <marco@descher.at>

4 files changed, 96 insertions, 9 deletions

diff --git a/bundles/org.eclipse.e4.tools.emf.ui/schema/org.eclipse.e4.tools.emf.ui.editors.exsd b/bundles/org.eclipse.e4.tools.emf.ui/schema/org.eclipse.e4.tools.emf.ui.editors.exsd
index 471aa288..a5b50e95 100644
--- a/bundles/org.eclipse.e4.tools.emf.ui/schema/org.eclipse.e4.tools.emf.ui.editors.exsd
+++ b/bundles/org.eclipse.e4.tools.emf.ui/schema/org.eclipse.e4.tools.emf.ui.editors.exsd
@@ -6,7 +6,14 @@
          <meta.schema plugin="org.eclipse.e4.tools.emf.ui" id="org.eclipse.e4.tools.emf.ui.editors" name="Editors"/>
       </appinfo>
       <documentation>
-         [Enter description of this extension point.]
+         Contribute editor(s), creation assistants and features for application model element(s).
+&lt;br&gt;&lt;br&gt;
+This extension point allows three distinct extensions:
+&lt;ul&gt;
+&lt;li&gt;Definition of (virtual) element editors&lt;/LI&gt;
+&lt;li&gt;Contribution of model element creation assistants&lt;/LI&gt;
+&lt;li&gt;Contribution of features for reference by existing model elements&lt;/LI&gt;
+&lt;/ul&gt;
       </documentation>
    </annotation>
 
@@ -51,11 +58,18 @@
    </element>
 
    <element name="editor">
+      <annotation>
+         <documentation>
+            Contribute an editor for a model element. Used to support editing new model elements not yet covered by the tooling.
+&lt;br&gt;&lt;br&gt;
+Editors contributed using this extension point override default editors.
+         </documentation>
+      </annotation>
       <complexType>
          <attribute name="descriptorClass" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  Defines the supported model element and returns a class capable of editing it.
                </documentation>
                <appinfo>
                   <meta.attribute kind="java" basedOn=":org.eclipse.e4.tools.emf.ui.common.IEditorDescriptor"/>
@@ -66,18 +80,25 @@
    </element>
 
    <element name="virtualeditor">
+      <annotation>
+         <documentation>
+            Contribute an editor for a virtual model element.
+&lt;br&gt;&lt;br&gt;
+A virtual model element is an element not backed by a real object. This is for example the case for editors defining the logical tree structure. These virtual editors may containireal model element objects. A concrete example is the virtual &lt;i&gt;Command Categories&lt;/i&gt; editor managing &lt;i&gt;MCategory&lt;/i&gt; objects.
+         </documentation>
+      </annotation>
       <complexType>
          <attribute name="id" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  The element id this virtual editor is used for.
                </documentation>
             </annotation>
          </attribute>
          <attribute name="class" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  An abstract visual editor class for the virtual model element. Use as basis to realize a virtual element editor.
                </documentation>
                <appinfo>
                   <meta.attribute kind="java" basedOn="org.eclipse.e4.tools.emf.ui.common.component.AbstractComponentEditor:"/>
@@ -88,11 +109,19 @@
    </element>
 
    <element name="editorfeature">
+      <annotation>
+         <documentation>
+            Contribute features castable to &lt;i&gt;class&lt;/i&gt; for reference by the application model.
+&lt;br&gt;&lt;br&gt;
+This is currently used to contribute &lt;i&gt;MExpression#visibleWhen&lt;/i&gt; and
+&lt;i&gt;ModelFragment#imports&lt;/i&gt; elements. So, for example, a custom &lt;i&gt;MExpression&lt;/i&gt; class could be contributed in order to provide a specific &lt;i&gt;visibleWhen&lt;/i&gt; rule.
+         </documentation>
+      </annotation>
       <complexType>
          <attribute name="class" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  Contributes the list of FeatureClass elements.
                </documentation>
                <appinfo>
                   <meta.attribute kind="java" basedOn=":org.eclipse.e4.tools.emf.ui.common.IEditorFeature"/>
@@ -103,11 +132,18 @@
    </element>
 
    <element name="contributionClassCreator">
+      <annotation>
+         <documentation>
+            Contribute an assistant for a model elements contribution class creation.
+&lt;br&gt;
+This assistant will be called by the element editor when instantiating a new contribution of the respective EClass.
+         </documentation>
+      </annotation>
       <complexType>
          <attribute name="class" type="string" use="required">
             <annotation>
                <documentation>
-                  
+                  Specifies the supported types and implements the creation and subsequent presentation of the newly created object in an editor.
                </documentation>
                <appinfo>
                   <meta.attribute kind="java" basedOn=":org.eclipse.e4.tools.emf.ui.common.IContributionClassCreator"/>
diff --git a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IContributionClassCreator.java b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IContributionClassCreator.java
index bbe72fed..a10da50d 100644
--- a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IContributionClassCreator.java
+++ b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IContributionClassCreator.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 BestSolution.at and others.
+ * Copyright (c) 2010-2014 BestSolution.at and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -7,6 +7,7 @@
  *
  * Contributors:
  *     Tom Schindl <tom.schindl@bestsolution.at> - initial API and implementation
+ *     Marco Descher <marco@descher.at> - Bug 424986 (Documentation)
  ******************************************************************************/
 package org.eclipse.e4.tools.emf.ui.common;
 
@@ -16,8 +17,30 @@ import org.eclipse.emf.ecore.EClass;
 import org.eclipse.emf.edit.domain.EditingDomain;
 import org.eclipse.swt.widgets.Shell;
 
+/**
+ * Contribute a creator for a certain type of {@link EClass}. The types
+ * supported by this creator are determined by querying
+ * {@link #isSupported(EClass)}.
+ */
 public interface IContributionClassCreator {
+	/**
+	 * Called to determine if the EClass is supported by the contribution
+	 *
+	 * @param element
+	 * @return <code>true</code> if supported
+	 */
 	public boolean isSupported(EClass element);
 
+	/**
+	 * Create and open editor for the model element. Called on the supported
+	 * creation of a new model element.
+	 *
+	 * @param contribution
+	 *            the {@link MContribution} element to be created and
+	 *            subsequently opened in the editor
+	 * @param domain
+	 * @param project
+	 * @param shell
+	 */
 	public void createOpen(MContribution contribution, EditingDomain domain, IProject project, Shell shell);
 }
diff --git a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorDescriptor.java b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorDescriptor.java
index 2d5fd342..e56685d6 100644
--- a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorDescriptor.java
+++ b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorDescriptor.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 BestSolution.at and others.
+ * Copyright (c) 2010-2014 BestSolution.at and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -7,13 +7,25 @@
  *
  * Contributors:
  *     Tom Schindl <tom.schindl@bestsolution.at> - initial API and implementation
+ *     Marco Descher <marco@descher.at> - Bug 424986 (Documentation)
  ******************************************************************************/
 package org.eclipse.e4.tools.emf.ui.common;
 
 import org.eclipse.emf.ecore.EClass;
 
+/**
+ * Contribute an editor for an application model element
+ */
 public interface IEditorDescriptor {
+	/**
+	 * @return supported model element
+	 */
 	public EClass getEClass();
 
+	/**
+	 * @return a class extending
+	 *         {@link org.eclipse.e4.tools.emf.ui.common.component.AbstractComponentEditor}
+	 *         capable of editing class returned in {@link #getEClass()}
+	 */
 	public Class<?> getEditorClass();
 }
diff --git a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorFeature.java b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorFeature.java
index 530f7b01..fdcf4cb0 100644
--- a/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorFeature.java
+++ b/bundles/org.eclipse.e4.tools.emf.ui/src/org/eclipse/e4/tools/emf/ui/common/IEditorFeature.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 BestSolution.at and others.
+ * Copyright (c) 2010-2014 BestSolution.at and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
@@ -7,6 +7,7 @@
  *
  * Contributors:
  *     Tom Schindl <tom.schindl@bestsolution.at> - initial API and implementation
+ *     Marco Descher <marco@descher.at> - Bug 424986 (Documentation)
  ******************************************************************************/
 package org.eclipse.e4.tools.emf.ui.common;
 
@@ -14,6 +15,9 @@ import java.util.List;
 import org.eclipse.emf.ecore.EClass;
 import org.eclipse.emf.ecore.EStructuralFeature;
 
+/**
+ * Contribute features for reference in the application model.
+ */
 public interface IEditorFeature {
 	public class FeatureClass {
 		public final String label;
@@ -25,5 +29,17 @@ public interface IEditorFeature {
 		}
 	}
 
+	/**
+	 * Return a list of {@link FeatureClass} elements, where
+	 * {@link FeatureClass#eClass} must be castable to <b>eClass</b> and will be
+	 * stored in <b>feature</b>.
+	 * 
+	 * @param eClass
+	 *            your contribution must be castable to
+	 * @param feature
+	 *            your contributions storage
+	 *            {@link org.eclipse.emf.ecore.EReference} target
+	 * @return the list of selectable alternatives for storage in <b>feature</b>
+	 */
 	public List<FeatureClass> getFeatureClasses(EClass eClass, EStructuralFeature feature);
 }