Bug 406918 - add noextend and noinstantiate I20130501-1100

Change-Id: Ifd3383fa2ad0f5b51bd5df05f32eb8b23abde685

17 files changed, 106 insertions, 28 deletions

diff --git a/bundles/org.eclipse.e4.ui.di/META-INF/MANIFEST.MF b/bundles/org.eclipse.e4.ui.di/META-INF/MANIFEST.MF
index 3fcd7e14fb5..d872af645e3 100644
--- a/bundles/org.eclipse.e4.ui.di/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.e4.ui.di/META-INF/MANIFEST.MF
@@ -4,17 +4,11 @@ Bundle-Name: %pluginName
 Bundle-Vendor: %providerName
 Bundle-Localization: plugin
 Bundle-SymbolicName: org.eclipse.e4.ui.di
-Bundle-Version: 0.11.0.qualifier
+Bundle-Version: 1.0.0.qualifier
 Bundle-RequiredExecutionEnvironment: J2SE-1.5
 Bundle-ActivationPolicy: lazy
 Import-Package: javax.inject;version="1.0.0"
-Export-Package: org.eclipse.e4.ui.di;
-  x-friends:="org.eclipse.e4.ui.workbench,
-   org.eclipse.ui.workbench,
-   org.eclipse.e4.core.contexts.debug,
-   org.eclipse.e4.ui.workbench.addons.swt,
-   org.eclipse.e4.ui.workbench.swt,
-   org.eclipse.e4.ui.workbench.renderers.swt",
+Export-Package: org.eclipse.e4.ui.di,
  org.eclipse.e4.ui.internal.di;x-internal:=true
 Require-Bundle: org.eclipse.e4.core.di;bundle-version="0.9.0",
  org.eclipse.e4.core.di.extensions;bundle-version="0.9.0",
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToHide.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToHide.java
index 11fbfa09e85..1fbcd33ba34 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToHide.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToHide.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2012 MEDEVIT, FHV and others.
+ * Copyright (c) 2012, 2013 MEDEVIT, FHV 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:
  *     Marco Descher <marco@descher.at> - initial API and implementation
+ *     IBM Corporation - bug fixes
  *******************************************************************************/
 package org.eclipse.e4.ui.di;
 
@@ -24,6 +25,7 @@ import java.lang.annotation.Target;
  * public void aboutToHide(List&lt;MMenuElement&gt; items) { }
  * 
  * @see org.eclipse.jface.action.IMenuListener2
+ * @since 1.0
  */
 @Documented
 @Target({ ElementType.METHOD })
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToShow.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToShow.java
index b3a74115d05..36b4b8212f9 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToShow.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/AboutToShow.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2012 MEDEVIT, FHV and others.
+ * Copyright (c) 2012, 2013 MEDEVIT, FHV 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:
  *     Marco Descher <marco@descher.at> - initial API and implementation
+ *     IBM Corporation - bug fixes
  *******************************************************************************/
 package org.eclipse.e4.ui.di;
 
@@ -24,6 +25,7 @@ import java.lang.annotation.Target;
  * public void aboutToShow(List&lt;MMenuElement&gt; items) { }
  * 
  * @see org.eclipse.jface.action.IMenuListener
+ * @since 1.0
  */
 @Documented
 @Target({ ElementType.METHOD })
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Focus.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Focus.java
index c3bc9cc8d7f..2f9813cea44 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Focus.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Focus.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 IBM Corporation and others.
+ * Copyright (c) 2010, 2013 IBM Corporation 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
@@ -24,6 +24,7 @@ import java.lang.annotation.Target;
  * multiple methods of the class are tagged with this this annotation, only one
  * of them will be called to grant focus to the part.
  * </p>
+ * @since 1.0
  */
 @Documented
 @Target({ ElementType.METHOD })
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Persist.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Persist.java
index 4885cb9a4e5..7b0edcb1974 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Persist.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/Persist.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 IBM Corporation and others.
+ * Copyright (c) 2010, 2013 IBM Corporation 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
@@ -23,6 +23,7 @@ import java.lang.annotation.Target;
  * This annotation must not be applied to more than one method on a class. If multiple methods of
  * the class are tagged with this this annotation, only one of them will be called to persist data.
  * </p>
+ * @since 1.0
  */
 @Documented
 @Target({ ElementType.METHOD })
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/PersistState.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/PersistState.java
index 6f6d3ff63c3..2ceaee11b5d 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/PersistState.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/PersistState.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2012 BestSolution.at and others.
+ * Copyright (c) 2012, 2013 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
+ *     IBM Corporation - bug fixes
  *******************************************************************************/
 package org.eclipse.e4.ui.di;
 
@@ -24,6 +25,7 @@ import java.lang.annotation.Target;
  * the class are tagged with this this annotation, only one of them will be called to persist visual 
  * state.
  * </p>
+ * @since 1.0
  */
 @Documented
 @Target({ ElementType.METHOD })
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UIEventTopic.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UIEventTopic.java
index c0766c2efc6..dfed54582ab 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UIEventTopic.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UIEventTopic.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010 IBM Corporation and others.
+ * Copyright (c) 2010, 2013 IBM Corporation 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
@@ -35,6 +35,7 @@ import javax.inject.Qualifier;
  * </pre>
  * 
  * </p>
+ * @since 1.0
  */
 @Qualifier
 @Documented
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UISynchronize.java b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UISynchronize.java
index 017eeb30263..2947b60f6f3 100644
--- a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UISynchronize.java
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/UISynchronize.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2011 BestSolution.at and others.
+ * Copyright (c) 2011, 2013 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,12 +7,16 @@
  *
  * Contributors:
  *     Tom Schindl <tom.schindl@bestsolution.at> - initial API and implementation
+ *     IBM Corporation - bug fixes
  *******************************************************************************/
 package org.eclipse.e4.ui.di;
 
 /**
  * Widget toolkit abstract to synchronize back into the UI-Thread from other
  * threads
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @since 1.0
  */
 public abstract class UISynchronize {
 	/**
diff --git a/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/package.html b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/package.html
new file mode 100644
index 00000000000..d07c38ba3ba
--- /dev/null
+++ b/bundles/org.eclipse.e4.ui.di/src/org/eclipse/e4/ui/di/package.html
@@ -0,0 +1,17 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+   <meta name="Author" content="IBM">
+   <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]">
+   <title>Package-level Javadoc</title>
+</head>
+<body>
+Application programming interfaces describing the Eclipse 4 dependency injection annotations.
+<h2>
+Package Specification</h2>
+<p>
+The package provides annotations for Eclipse 4 dependency injection.
+</p>
+</body>
+</html>
diff --git a/bundles/org.eclipse.e4.ui.workbench/META-INF/MANIFEST.MF b/bundles/org.eclipse.e4.ui.workbench/META-INF/MANIFEST.MF
index f13253943ae..324558c4cee 100644
--- a/bundles/org.eclipse.e4.ui.workbench/META-INF/MANIFEST.MF
+++ b/bundles/org.eclipse.e4.ui.workbench/META-INF/MANIFEST.MF
@@ -30,11 +30,7 @@ Export-Package: org.eclipse.e4.ui.internal.workbench;
    org.eclipse.ui.workbench",
  org.eclipse.e4.ui.internal.workbench.addons;x-internal:=true,
  org.eclipse.e4.ui.internal.workbench.handlers;x-internal:=true,
- org.eclipse.e4.ui.workbench;
-  x-friends:="org.eclipse.e4.ui.workbench.swt,
-   org.eclipse.e4.ui.workbench.addons.swt,
-   org.eclipse.e4.ui.workbench.renderers.swt,
-   org.eclipse.ui.workbench",
+ org.eclipse.e4.ui.workbench,
  org.eclipse.e4.ui.workbench.lifecycle;x-friends:="org.eclipse.e4.ui.workbench.swt",
  org.eclipse.e4.ui.workbench.modeling
 Bundle-Activator: org.eclipse.e4.ui.internal.workbench.Activator
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IExceptionHandler.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IExceptionHandler.java
index 7cd086b8ac7..4866d7e251a 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IExceptionHandler.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IExceptionHandler.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009 IBM Corporation and others.
+ * Copyright (c) 2009, 2013 IBM Corporation 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
@@ -10,6 +10,19 @@
  *******************************************************************************/
 package org.eclipse.e4.ui.workbench;
 
+/**
+ * This handler allows clients to be notified when an exception occurs
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @since 1.0
+ */
 public interface IExceptionHandler {
+
+	/**
+	 * Call-back to handle the given {@link Throwable}
+	 * 
+	 * @param e
+	 *            the {@link Throwable}
+	 */
 	public void handleException(Throwable e);
 }
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IModelResourceHandler.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IModelResourceHandler.java
index 955020845aa..a522fe5fc10 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IModelResourceHandler.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IModelResourceHandler.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2010,2013 IBM Corporation and others.
+ * Copyright (c) 2010, 2013 IBM Corporation 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
@@ -19,14 +19,19 @@ import org.eclipse.e4.ui.model.application.MApplication;
 import org.eclipse.emf.ecore.resource.Resource;
 
 /**
- *
+ * This handler allows clients load, create and save model resources
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @since 1.0
  */
 public interface IModelResourceHandler {
 
 	/**
+	 * Loads an returns the most recent model that was persisted
+	 * 
 	 * @return the most recent model state
 	 */
-	Resource loadMostRecentModel();
+	public Resource loadMostRecentModel();
 
 	/**
 	 * Creates a resource with an app Model, used for saving copies of the main app model.
@@ -38,10 +43,12 @@ public interface IModelResourceHandler {
 	public Resource createResourceWithApp(MApplication theApp);
 
 	/**
+	 * Saves the model
+	 * 
 	 * @throws IOException
 	 *             if storing fails
 	 * 
 	 */
-	void save() throws IOException;
+	public void save() throws IOException;
 
 }
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IPresentationEngine.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IPresentationEngine.java
index 0f172e90e7b..73763ddc47d 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IPresentationEngine.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IPresentationEngine.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009, 2012 BestSolution.at and others.
+ * Copyright (c) 2009, 2013 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
@@ -21,6 +21,9 @@ import org.eclipse.e4.ui.model.application.ui.MUIElement;
  * Implementations of this service are responsible for creating or destroying widgets corresponding
  * to model elements, as well as for running any event loop required for handling user events on
  * those widgets.
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @since 1.0
  */
 public interface IPresentationEngine {
 	/**
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IResourceUtilities.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IResourceUtilities.java
index dda18f8c5d7..850df500af8 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IResourceUtilities.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IResourceUtilities.java
@@ -1,5 +1,5 @@
 /*******************************************************************************
- * Copyright (c) 2009, 2010 IBM Corporation and others.
+ * Copyright (c) 2009, 2013 IBM Corporation 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
@@ -14,10 +14,21 @@ package org.eclipse.e4.ui.workbench;
 import org.eclipse.emf.common.util.URI;
 
 /**
- *
+ * This interface describes a utility that is used to load ImageDesc's from {@link URI}s
+ * 
+ * @param <ImageDesc>
+ * 
+ * @noimplement This interface is not intended to be implemented by clients.
+ * @since 1.0
  */
 public interface IResourceUtilities<ImageDesc> {
 
+	/**
+	 * Loads an ImageDesc from the given {@link URI}.
+	 * 
+	 * @param iconPath
+	 * @return the ImageDesc from the given URI or <code>null</code>
+	 */
 	public ImageDesc imageDescriptorFromURI(URI iconPath);
 
 }
\ No newline at end of file
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IWorkbench.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IWorkbench.java
index 31bb85f423c..2741d485764 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IWorkbench.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/IWorkbench.java
@@ -25,6 +25,9 @@ import org.eclipse.e4.ui.model.application.MApplication;
  * </ul>
  * <b>It is possible that there are multiple active {@link IWorkbench} instances in one
  * OSGi-Instance</b>
+ * 
+ * @since 1.0
+ * @noimplement This interface is not intended to be implemented by clients.
  */
 public interface IWorkbench {
 	/**
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/UIEvents.java b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/UIEvents.java
index 0e3f2669426..a9f3ae9ea84 100644
--- a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/UIEvents.java
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/UIEvents.java
@@ -29,6 +29,10 @@ import org.osgi.service.event.Event;
  * When the UI model changes org.eclipse.e4.ui.internal.workbench.swt.GenTopic should be run as an
  * Eclipse application and the console results should be pasted into this file replacing the code
  * below the "Place Generated Code Here" comment
+ * 
+ * @noextend This class is not intended to be subclassed by clients.
+ * @noinstantiate This class is not intended to be instantiated by clients.
+ * @since 1.0
  */
 public class UIEvents {
 
diff --git a/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/package.html b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/package.html
new file mode 100644
index 00000000000..cb604e9b5a4
--- /dev/null
+++ b/bundles/org.eclipse.e4.ui.workbench/src/org/eclipse/e4/ui/workbench/package.html
@@ -0,0 +1,17 @@
+<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
+<html>
+<head>
+   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+   <meta name="Author" content="IBM">
+   <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]">
+   <title>Package-level Javadoc</title>
+</head>
+<body>
+Application programming interfaces describing Eclipse 4 handlers and the workbench.
+<h2>
+Package Specification</h2>
+<p>
+The package provides interfaces describing Eclipse 4 handlers, the workbench and the event sets for the workbench.
+</p>
+</body>
+</html>