cleanup and review => YELLOW, GREEN

refs 311

org.fortiss.tooling.kernel.ui/trunk/src/org/fortiss/tooling/kernel/ui/internal/views/MarkerViewPart.java

@@ -56,7 +56,7 @@ import org.fortiss.tooling.kernel.ui.service.IModelElementHandlerService;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating YELLOW Hash: D704B64672A237813BBE842E17869E76
+ * @ConQAT.Rating GREEN Hash: EAE8E1FB9FBA7562BF9DA666337C68C9
  */
 public class MarkerViewPart extends ViewPart {
 

org.fortiss.tooling.kernel/trunk/src/org/fortiss/tooling/kernel/extension/data/ITopLevelElement.java

@@ -24,13 +24,20 @@ import org.eclipse.core.runtime.IProgressMonitor;
 import org.eclipse.emf.common.command.CommandStackListener;
 import org.eclipse.emf.ecore.EObject;
 import org.fortiss.tooling.kernel.extension.IStorageProvider;
+import org.fortiss.tooling.kernel.service.IPersistencyService;
 
 /**
  * Interface for accessing top-level elements provided by
  * {@link IStorageProvider}s. This interface supports the typical methods like
  * running commands, listening to the command stack, undo and redo, a dirty
  * state and a save mechanism as well as accessing the root model element.
- * 
+ * <P>
+ * Since some storage providers may supply an EObject as root model element,
+ * which is contained in some other EObject, users of the kernel cannot assume
+ * that the top-most EObject is also the root of one model (e.g. a project).
+ * They must rely on the {@link IPersistencyService} to determine the scope of
+ * one model. Everything wrapped by instances of this class are considered to be
+ * one model from the kernel's point of view.
  * <P>
  * Once an instance of this interface is provided to the kernel, the underlying
  * load must be completed successfully. Failure during the model loading must be
@@ -40,19 +47,20 @@ import org.fortiss.tooling.kernel.extension.IStorageProvider;
  * @author hoelzl
  * @author $Author$
  * @version $Rev$
- * @ConQAT.Rating GREEN Hash: 627F8F0B59A57FB8FE9CD20F70C02C7F
+ * @ConQAT.Rating YELLOW Hash: EA2DFF41F36A0C0628BA6D8ACD484BD0
  */
 public interface ITopLevelElement {
 
 	/** Returns the root model element represented by this top-level element. */
-	// TODO: vielleicht wäre ne Definition, was ein Top-Level-Element und was
-	// ein Root-Element ist, nett. Es wäre auf jeden Fall hilfreich, da das
-	// keine 100% selbsterklärenden Begriffe sind.
 	EObject getRootModelElement();
 
-	/** Executes the given {@link Runnable} as model changing command. */
-	// TODO: warum model changing? Was für ein Model wird wie geändert und warum
-	// kommt das im Methodennamen nicht vor?
+	/**
+	 * Executes the given {@link Runnable} as model changing command on the
+	 * underlying command stack. All model changes must run in a EMF
+	 * transaction. This method wraps the runnable in such a transaction and
+	 * applies the changes to the EMF model. Completed transactions can be
+	 * undone and/or redone.
+	 */
 	void runAsCommand(Runnable runner);
 
 	/**