[misc] Consolidated @Clumsy, @Experimental, and @Provisional annotations.refs/changes/02/8302/3

Change-Id: I132951e693a3b02600347ddac75541b289e5de8d

6 files changed, 11 insertions, 76 deletions

diff --git a/plugins/org.eclipse.recommenders.completion.rcp.calls/src/org/eclipse/recommenders/internal/completion/rcp/calls/extdoc/CallsProvider.java b/plugins/org.eclipse.recommenders.completion.rcp.calls/src/org/eclipse/recommenders/internal/completion/rcp/calls/extdoc/CallsProvider.java
index 786bafd..5af5a11 100644
--- a/plugins/org.eclipse.recommenders.completion.rcp.calls/src/org/eclipse/recommenders/internal/completion/rcp/calls/extdoc/CallsProvider.java
+++ b/plugins/org.eclipse.recommenders.completion.rcp.calls/src/org/eclipse/recommenders/internal/completion/rcp/calls/extdoc/CallsProvider.java
@@ -44,7 +44,7 @@ import org.eclipse.recommenders.internal.utils.codestructs.DefinitionSite.Kind;
 import org.eclipse.recommenders.rcp.events.JavaSelectionEvent;
 import org.eclipse.recommenders.utils.Names;
 import org.eclipse.recommenders.utils.Tuple;
-import org.eclipse.recommenders.utils.annotations.Experimental;
+import org.eclipse.recommenders.utils.annotations.Provisional;
 import org.eclipse.recommenders.utils.names.IMethodName;
 import org.eclipse.recommenders.utils.names.VmMethodName;
 import org.eclipse.recommenders.utils.rcp.JavaElementResolver;
@@ -59,12 +59,7 @@ import org.eclipse.swt.widgets.Link;
 import com.google.common.base.Optional;
 import com.google.common.eventbus.EventBus;
 
-/**
- * Experimental code.
- * <p>
- * XXX MB: this is dark force code... need to clean it up after provider layout fixed.
- */
-@Experimental
+@Provisional("Experimental code; needs to be cleaned up after provider layout is fixed.")
 public final class CallsProvider extends ExtdocProvider {
 
     private final IModelArchiveStore<IType, IObjectMethodCallsNet> modelStore;
diff --git a/plugins/org.eclipse.recommenders.completion.rcp.e37/src/org/eclipse/recommenders/internal/completion/rcp/CompilerAstCompletionNodeFinder.java b/plugins/org.eclipse.recommenders.completion.rcp.e37/src/org/eclipse/recommenders/internal/completion/rcp/CompilerAstCompletionNodeFinder.java
index c14cdbb..06b18b3 100644
--- a/plugins/org.eclipse.recommenders.completion.rcp.e37/src/org/eclipse/recommenders/internal/completion/rcp/CompilerAstCompletionNodeFinder.java
+++ b/plugins/org.eclipse.recommenders.completion.rcp.e37/src/org/eclipse/recommenders/internal/completion/rcp/CompilerAstCompletionNodeFinder.java
@@ -126,13 +126,13 @@ import org.eclipse.jdt.internal.compiler.lookup.MethodBinding;
 import org.eclipse.jdt.internal.compiler.lookup.MethodScope;

 import org.eclipse.jdt.internal.compiler.lookup.TypeBinding;

 import org.eclipse.jdt.internal.compiler.lookup.VariableBinding;

-import org.eclipse.recommenders.utils.annotations.Clumsy;

+import org.eclipse.recommenders.utils.annotations.Provisional;

 

 import com.google.common.collect.Iterables;

 import com.google.common.collect.Lists;

 import com.google.common.collect.Sets;

 

-@Clumsy

+@Provisional

 @SuppressWarnings("restriction")

 public class CompilerAstCompletionNodeFinder extends ASTVisitor {

 

diff --git a/plugins/org.eclipse.recommenders.extdoc/src/org/eclipse/recommenders/extdoc/ClassOverridePatterns.java b/plugins/org.eclipse.recommenders.extdoc/src/org/eclipse/recommenders/extdoc/ClassOverridePatterns.java
index f7b30aa..b4927e9 100644
--- a/plugins/org.eclipse.recommenders.extdoc/src/org/eclipse/recommenders/extdoc/ClassOverridePatterns.java
+++ b/plugins/org.eclipse.recommenders.extdoc/src/org/eclipse/recommenders/extdoc/ClassOverridePatterns.java
@@ -33,7 +33,7 @@ public final class ClassOverridePatterns {
         return res;

     }

 

-    @Provisional(discussAPI = "Capture of null only for testing resons")

+    @Provisional("Capture of null only for testing resons")

     public MethodPattern[] getPatterns() {

         return patterns == null ? new MethodPattern[0] : patterns.clone();

     }

diff --git a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Clumsy.java b/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Clumsy.java
deleted file mode 100644
index 7686835..0000000
--- a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Clumsy.java
+++ b/dev/null
@@ -1,33 +0,0 @@
-/**
- * Copyright (c) 2010 Darmstadt University of Technology.
- * 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
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *    Marcel Bruch - initial API and implementation.
- */
-package org.eclipse.recommenders.utils.annotations;
-
-import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * This code is in constant flux and by no means reusable by others. In other
- * words: "here we hack! Don't use this code nor consider it as being stable. It
- * will change ASAP and without notice.</b>
- */
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PACKAGE })
-@Inherited
-public @interface Clumsy {
-    String discussAPI() default "http://eclipse.org/projects/recommenders/";
-
-    String reportIssues() default "http://eclipse.org/projects/recommenders/bugs";
-}
diff --git a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Experimental.java b/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Experimental.java
deleted file mode 100644
index 8c10f36..0000000
--- a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Experimental.java
+++ b/dev/null
@@ -1,30 +0,0 @@
-/**
- * Copyright (c) 2010 Darmstadt University of Technology.
- * 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
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- *    Marcel Bruch - initial API and implementation.
- */
-package org.eclipse.recommenders.utils.annotations;
-
-import java.lang.annotation.Documented;
-import java.lang.annotation.ElementType;
-import java.lang.annotation.Inherited;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-/**
- * This API element is very experimental and is likely to change in the near
- * future.
- * 
- */
-@Documented
-@Retention(RetentionPolicy.SOURCE)
-@Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PACKAGE })
-@Inherited
-public @interface Experimental {
-}
diff --git a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Provisional.java b/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Provisional.java
index 387d980..bbba4da 100644
--- a/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Provisional.java
+++ b/plugins/org.eclipse.recommenders.utils/src/org/eclipse/recommenders/utils/annotations/Provisional.java
@@ -18,14 +18,17 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Members annotated with this annotation are considered to be very likely to change.
+ * Members annotated with this annotation are considered to be very likely to change; do
+ * not depend on them.
  */
 @Documented
 @Retention(RetentionPolicy.SOURCE)
 @Target({ ElementType.TYPE, ElementType.METHOD, ElementType.CONSTRUCTOR, ElementType.PACKAGE })
 @Inherited
 public @interface Provisional {
-    String discussAPI() default "http://eclipse.org/projects/recommenders/";
 
-    String reportIssues() default "http://eclipse.org/projects/recommenders/bugs";
+    /**
+     * The reason why the annotated element is provisional.
+     */
+    String value() default "";
 }