improved kernel implementation documentation (package.html and javadoc)

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/ModelElementHandlerBase.java

@@ -28,16 +28,22 @@ import org.fortiss.tooling.kernel.ui.interfaces.IModelElementHandler;
 /**
  * Base implementation for {@link IModelElementHandler}s.
  * 
+ * Sub-classes must implement {@link #getIconImageDescriptor()} and may override
+ * the other methods of {@link IModelElementHandler}. By default the base
+ * implementation returns empty lists for the respective methods.
+ * 
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 917041660DD89A42589D65ED4EDF5CF2
+ * @ConQAT.Rating YELLOW Hash: 0DE800FFBC75165394F36B6993C49EB7
  */
 public abstract class ModelElementHandlerBase<T extends EObject> implements
 		IModelElementHandler<T> {
 
-	// @TODO: why 'singleton' ?
-	/** Stores the singleton of the icon image. */
+	/**
+	 * Stores of the icon image. Use singleton to save the limited image
+	 * buffers.
+	 */
 	private Image iconImage;
 
 	/** {@inheritDoc} */

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/PropertySectionBase.java

@@ -33,6 +33,7 @@ import org.eclipse.swt.widgets.Text;
 import org.eclipse.ui.IWorkbenchPart;
 import org.eclipse.ui.views.properties.tabbed.AbstractPropertySection;
 import org.eclipse.ui.views.properties.tabbed.TabbedPropertySheetPage;
+import org.fortiss.tooling.kernel.ui.util.DataBindingUtils;
 
 /**
  * Base class for property sections, dealing with setting the input and
@@ -41,7 +42,7 @@ import org.eclipse.ui.views.properties.tabbed.TabbedPropertySheetPage;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating RED Hash: 796851A7B16A7BEB1C3AAD577BF565CB
+ * @ConQAT.Rating YELLOW Hash: D5B6D00C04A15A9C865F846631FA082B
  */
 public abstract class PropertySectionBase extends AbstractPropertySection {
 
@@ -90,17 +91,15 @@ public abstract class PropertySectionBase extends AbstractPropertySection {
 	/** This is used to set the single section input. The parameter may be null! */
 	protected abstract void setSectionInput(Object input);
 
-	// @TODO: missing the implementation
 	/**
 	 * Creates a text widget, which has a {@link ControlDecoration} attached.
 	 * The decoration is stored as widget data for convenience.
 	 */
 	protected Text createDecoratedText(String labelText) {
-		// final Text text = createFormText(labelText);
-		// text.setData(DataBindingUtils.DECORATION_KEY, new ControlDecoration(
-		// text, SWT.LEFT | SWT.TOP));
-		// return text;
-		return null;
+		Text text = createFormText(labelText);
+		text.setData(DataBindingUtils.DECORATION_KEY, new ControlDecoration(
+				text, SWT.LEFT | SWT.TOP));
+		return text;
 	}
 
 	/** Creates form text field. */

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IActionContributingEditor.java

@@ -27,20 +27,19 @@ import org.fortiss.tooling.kernel.ui.internal.editor.BindingContributor;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: F21F807F121EFD17352A1BBDEA5609B8
+ * @ConQAT.Rating YELLOW Hash: 4644FCF70CA34FD1D20CFB174FD4E4A4
  */
 public interface IActionContributingEditor {
 	/**
-	 * This method is a hook to register additional actions in an editor. This
-	 * base implementation is empty. The implementation of this should match
-	 * with the implementation of {@link #unregisterGlobalActions(IActionBars)}.
+	 * This method is a hook to register additional actions in an editor.The
+	 * implementation of this should match with the implementation of
+	 * {@link #unregisterGlobalActions(IActionBars)}.
 	 */
 	void registerGlobalActions(IActionBars bars);
 
 	/**
 	 * This method is a hook to unregister actions registered in
-	 * {@link #registerGlobalActions(IActionBars)}. This base implementation is
-	 * empty.
+	 * {@link #registerGlobalActions(IActionBars)}.
 	 */
 	void unregisterGlobalActions(IActionBars bars);
 }

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditPartFactory.java

@@ -19,16 +19,18 @@ package org.fortiss.tooling.kernel.ui.interfaces;
 
 import org.eclipse.emf.ecore.EObject;
 import org.eclipse.gef.EditPartFactory;
+import org.fortiss.tooling.kernel.base.EObjectAwareServiceBase;
 import org.fortiss.tooling.kernel.interfaces.IEObjectAware;
 
 /**
  * This is a wrapper interface for {@link EditPartFactory}. It is necessary in
- * order to use the {@link IEObjectAware} base implementation.
+ * order to use {@link IEObjectAware} and the {@link EObjectAwareServiceBase}
+ * implementation.
  * 
  * @author hoelzlf
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: FCE65AE37C2C903EEDB13E0B39F3B55D
+ * @ConQAT.Rating YELLOW Hash: E20E3FBA08256173AF0B9538151BB880
  */
 public interface IEditPartFactory<T extends EObject> extends IEObjectAware<T>,
 		EditPartFactory {

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditorBinding.java

@@ -20,14 +20,23 @@ package org.fortiss.tooling.kernel.ui.interfaces;
 import org.eclipse.emf.ecore.EObject;
 import org.eclipse.ui.IEditorPart;
 import org.fortiss.tooling.kernel.interfaces.IEObjectAware;
+import org.fortiss.tooling.kernel.ui.services.IEditorService;
 
 /**
- * Interface for editor bindings.
+ * Interface for editor bindings. An editor binding a defines a model element
+ * editor. Usually, an editor (in the Eclipse interpretation) is a view (in the
+ * model-based development interpretation) on the underlying model.
+ * 
+ * <P>
+ * Each editor provided by some binding becomes part of an Eclipse multi-page
+ * editor. Its page carries the name delivered by {@link #getLabel()}. The
+ * {@link IEditorService} sorts the provided editors according to their priority
+ * returned by {@link #getPriority()} with higher values having lower priority.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 7E389CB6937BF93467517F49FEC75BCA
+ * @ConQAT.Rating YELLOW Hash: 824E83F523001E7C530E89FB1F5B5C5B
  */
 public interface IEditorBinding<T extends EObject> extends
 		IEObjectAware<EObject> {

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IModelElementHandler.java

@@ -23,15 +23,20 @@ import org.eclipse.emf.ecore.EObject;
 import org.eclipse.jface.resource.ImageDescriptor;
 import org.eclipse.swt.graphics.Image;
 import org.fortiss.tooling.kernel.interfaces.IEObjectAware;
+import org.fortiss.tooling.kernel.ui.base.ModelElementHandlerBase;
+import org.fortiss.tooling.kernel.ui.base.NamedCommentedModelElementHandlerBase;
 
 /**
  * A model element handler provides information about a specific type of model
- * elements.
+ * elements like name, description, icon and certain kinds of sub-elements.
+ * 
+ * @see ModelElementHandlerBase
+ * @see NamedCommentedModelElementHandlerBase
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 02238EA9A8F42D8C9C21B463606C8A2D
+ * @ConQAT.Rating YELLOW Hash: 8FE024CE59C8A27348CCD343671DC7D7
  */
 public interface IModelElementHandler<T extends EObject> extends
 		IEObjectAware<T> {

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditPartFactoryService.java

@@ -18,16 +18,18 @@ $Id$
 package org.fortiss.tooling.kernel.ui.services;
 
 import org.eclipse.gef.EditPartFactory;
+import org.fortiss.tooling.kernel.ui.interfaces.IEditPartFactory;
 import org.fortiss.tooling.kernel.ui.internal.EditPartFactoryService;
 
 /**
- * The prototype service provides registration and access to model element
- * prototypes.
+ * The edit part factory service provides registration of
+ * {@link IEditPartFactory}s. The service is itself and {@link EditPartFactory}
+ * and can therefore be used as factory for all GEF-based graphical editors.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: F01D48DCA4F80858F39646340CE0E5F2
+ * @ConQAT.Rating YELLOW Hash: 465A71657359ABBCD0BE5F70815436B1
  */
 public interface IEditPartFactoryService extends EditPartFactory {
 

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditorService.java

@@ -24,12 +24,15 @@ import org.fortiss.tooling.kernel.ui.interfaces.IEditorBinding;
 import org.fortiss.tooling.kernel.ui.internal.EditorService;
 
 /**
- * The editor service handles editor registration and double-click support.
+ * The editor service handles editor registration. It also allows opening and
+ * closing of editors.
+ * 
+ * @see IEditorBinding
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 2C420A3D582F2726FBC96D141CEAEF81
+ * @ConQAT.Rating YELLOW Hash: ECCFA2C956D54381EC206F79876D8BC1
  */
 public interface IEditorService {
 

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IModelElementService.java

@@ -25,10 +25,12 @@ import org.fortiss.tooling.kernel.ui.internal.ModelElementService;
  * The model context service provides information about registered model
  * elements.
  * 
+ * @see IModelElementHandler
+ * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 84FA1569F479C2625D09D0CA2C9A170D
+ * @ConQAT.Rating YELLOW Hash: F470AE8CE0B8E2DA47B0099EDC4BFA88
  */
 public interface IModelElementService {
 

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/INavigatorService.java

@@ -23,12 +23,19 @@ import org.eclipse.ui.Saveable;
 import org.fortiss.tooling.kernel.ui.internal.NavigatorService;
 
 /**
- * The navigator service provides model navigation support.
+ * The navigator service provides model navigation support. Its main
+ * contribution is the navigator Eclipse view, which shows the model content
+ * starting with the top-level elements and using the information provided by
+ * {@link IModelElementService}.
+ * 
+ * <P>
+ * The navigator service is also responsible to integrate with the Eclipse IDE
+ * regarding model file save support.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: E84D4BEC9A2F32EAF84A8FDCF21EE3F4
+ * @ConQAT.Rating YELLOW Hash: 66B5DD3650C883C2E70023247D11A811
  */
 public interface INavigatorService {
 	/** Returns the singleton instance of the service. */

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IPropertiesService.java

@@ -17,15 +17,31 @@ $Id$
 +--------------------------------------------------------------------------*/
 package org.fortiss.tooling.kernel.ui.services;
 
+import org.fortiss.tooling.kernel.model.IIdLabeled;
+import org.fortiss.tooling.kernel.model.INamedCommentedElement;
+import org.fortiss.tooling.kernel.ui.base.PropertySectionBase;
 import org.fortiss.tooling.kernel.ui.internal.PropertiesService;
 
 /**
  * The properties service manages model element specific properties.
+ * <P>
+ * This class is a facade providing the IDs to be used with the tabbed property
+ * framework. Property sections should consider to use
+ * {@link PropertySectionBase} as a starting point for property sections.
+ * 
+ * <P>
+ * By default, the kernel registers to property tabs. The
+ * <code>org.fortiss.tooling.kernel.ui.property.tab.general</code> tab supports
+ * a default section for {@link INamedCommentedElement} with editing support for
+ * <code>name</code> and <code>comment</code>. The
+ * <code>org.fortiss.tooling.kernel.ui.property.tab.internal</code> tab shows
+ * the unique internal ID of an {@link IIdLabeled} model element. This ID cannot
+ * be changed manually.
  * 
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: 102C35BC9B6C4C7BFE71810750CD4D20
+ * @ConQAT.Rating YELLOW Hash: 2A09E8B8BA89FFD035F4D9AE28DCE6AA
  */
 public interface IPropertiesService {