From f85bd6077ce6d0cd08f819d7a2bca3df1537eded Mon Sep 17 00:00:00 2001
From: Florian Hoelzl <hoelzl@fortiss.org>
Date: Mon, 4 Jul 2011 10:09:00 +0000
Subject: [PATCH] improved kernel implementation documentation (package.html
and javadoc)
---
.../ui/base/ModelElementHandlerBase.java | 12 +++++++++---
.../kernel/ui/base/PropertySectionBase.java | 13 ++++++-------
.../interfaces/IActionContributingEditor.java | 11 +++++------
.../kernel/ui/interfaces/IEditPartFactory.java | 6 ++++--
.../kernel/ui/interfaces/IEditorBinding.java | 13 +++++++++++--
.../ui/interfaces/IModelElementHandler.java | 9 +++++++--
.../ui/services/IEditPartFactoryService.java | 8 +++++---
.../kernel/ui/services/IEditorService.java | 7 +++++--
.../ui/services/IModelElementService.java | 4 +++-
.../kernel/ui/services/INavigatorService.java | 11 +++++++++--
.../kernel/ui/services/IPropertiesService.java | 18 +++++++++++++++++-
11 files changed, 81 insertions(+), 31 deletions(-)
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/ModelElementHandlerBase.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/ModelElementHandlerBase.java
index a43fe2097..b83c68615 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/ModelElementHandlerBase.java
+++ b/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} */
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/PropertySectionBase.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/PropertySectionBase.java
index 81c1b46fe..be5ed22fd 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/base/PropertySectionBase.java
+++ b/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. */
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IActionContributingEditor.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IActionContributingEditor.java
index 719b306fc..21419cc6c 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IActionContributingEditor.java
+++ b/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);
}
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditPartFactory.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditPartFactory.java
index 29d67e88e..2e32d5db3 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditPartFactory.java
+++ b/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 {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditorBinding.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditorBinding.java
index c6d6699c5..8fac28eb7 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IEditorBinding.java
+++ b/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> {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IModelElementHandler.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IModelElementHandler.java
index 7ca478ad7..bc97440a7 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/interfaces/IModelElementHandler.java
+++ b/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> {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditPartFactoryService.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditPartFactoryService.java
index 39f15065b..26399f0dd 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditPartFactoryService.java
+++ b/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 {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditorService.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditorService.java
index 8b9f5abd5..562f6893a 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IEditorService.java
+++ b/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 {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IModelElementService.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IModelElementService.java
index 828a5136e..c178e91d0 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IModelElementService.java
+++ b/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 {
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/INavigatorService.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/INavigatorService.java
index 5b9cc1418..92092efbe 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/INavigatorService.java
+++ b/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. */
diff --git a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IPropertiesService.java b/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IPropertiesService.java
index a189acf5b..c33f17c28 100644
--- a/org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/services/IPropertiesService.java
+++ b/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 {
--
GitLab