Bug 495737 - Update the JavaDoc on SubMonitor and IProgressMonitor to

reflect the 4.7 calling conventions.

Change-Id: If7a5a3d5bfa8de4bcb625b0face6172d01bacdf2
Signed-off-by: Stefan Xenos <sxenos@gmail.com>

2 files changed, 30 insertions, 55 deletions

diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
index 12a9dd622..bc601b23d 100644
--- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
+++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/IProgressMonitor.java
@@ -38,7 +38,36 @@ package org.eclipse.core.runtime;
  * involve blocking operations, or operations which might throw uncaught exceptions, 
  * the notifications should be queued, and the actual processing deferred (or perhaps
  * delegated to a separate thread).
- * </p><p>
+ * </p>
+ * <p><b>CALLER/CALLEE RESPONSIBILITIES:</b></p>
+ * <p>
+ * Methods that receive an {@link IProgressMonitor} must either obey the following
+ * conventions or include JavaDoc explaining how it differs from these rules.
+ * The called method:
+ * <ul>
+ * <li>Will call {@link #beginTask} on the argument 0 or 1 times, at its option.</li>
+ * <li>Will not promise to invoke {@link #done()} on the monitor.</li>
+ * <li>Will not call {@link #setCanceled} on the monitor.</li>
+ * <li>May rely on the monitor not being null.</li>
+ * <li>May rely on the monitor ignoring the string passed to {@link #beginTask}.</li>
+ * </ul>
+ * <p>
+ * The caller:
+ * <ul>
+ * <li>Will either pass in a fresh instance of {@link IProgressMonitor} that has
+ *     not had {@link #beginTask} invoked on it yet, or will select an
+ *     implementation of {@link IProgressMonitor} that explicitly permits multiple calls
+ *     to {@link #beginTask}.</li>
+ * <li>Will not rely on the callee to invoke {@link #done()} on the monitor.
+ *     It must either select an implementation of {@link IProgressMonitor} that
+ *     does not require {@link #done()} to be called, for example {@link SubMonitor},
+ *     or it must invoke {@link #done()} itself after the method returns.</li>
+ * <li>Will not pass in a null monitor unless the JavaDoc of the callee says that it
+ *     accepts null.</li>
+ * <li>Will pass in a monitor that ignores the name argument to {@link #beginTask}
+ *     unless the JavaDoc for the callee states otherwise.
+ * </ul>
+ * 
  * This interface can be used without OSGi running.
  * </p><p>
  * Clients may implement this interface.
diff --git a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
index 47500fd60..02bb70da7 100644
--- a/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
+++ b/bundles/org.eclipse.equinox.common/src/org/eclipse/core/runtime/SubMonitor.java
@@ -45,31 +45,7 @@ import org.eclipse.core.internal.runtime.TracingOptions;
  * <li>Use <code>SubMonitor.split(...)</code> whenever you need to call another method that 
  * accepts an IProgressMonitor.</li>
  * </ul>
- * <p></p>
- * <p><b>DEFAULT BEHAVIOR:</b></p>
  * 
- * <p>When writing JavaDoc for a method that accepts an IProgressMonitor, you should assume the 
- * following default behavior unless the method's JavaDoc says otherwise:</p>
- * <ul>
- * <li>It WILL call beginTask on the IProgressMonitor.</li>
- * <li>It WILL NOT accept a null argument.</li>
- * <li>It WILL call done on the IProgressMonitor.</li>
- * </ul>
- * <p></p>
- * <p><b>BEST PRACTISES:</b></p>
- * 
- * <p>We recommend that newly-written methods follow the given contract:</p>
- * <ul>
- * <li>It WILL call beginTask on the IProgressMonitor.</li>
- * <li>It WILL accept a null argument, indicating that no progress should be reported and the operation cannot be cancelled.</li>
- * <li>It WILL NOT call done on the IProgressMonitor, leaving this responsibility up to the caller.</li>
- * </ul>
- * <p>If you wish to follow these conventions, you may copy and paste the following text into your method's JavaDoc:</p>
- * 
- * <pre>@param monitor the progress monitor to use for reporting progress to the user. It is the caller's responsibility
- *        to call done() on the given monitor. Accepts <code>null</code>, indicating that no progress should be
- *        reported and that the operation cannot be cancelled.</pre>
- *
  * <p></p>
  * <p><b>Example: Recommended usage</b></p>
  *
@@ -99,36 +75,6 @@ import org.eclipse.core.internal.runtime.TracingOptions;
  *          doSomeWork(progress.split(40)); 
  *      }
  * </pre>
- *
- *
- * <p></p>
- * <p><b>Example: Default usage</b></p>
- * 
- * <p>You will often need to implement a method that does not explicitly stipulate that calling done() is the responsibility
- * of the caller. In this case, you should use the following pattern:</p>
- * 
- * <pre>
- *      // param monitor the progress monitor to use for reporting progress to the user, or <code>null</code> indicating
- *      //        that no progress should be reported and the operation cannot be cancelled.
- *      //
- *      void doSomething(IProgressMonitor monitor) {
- *          // Convert the given monitor into a progress instance 
- *          SubMonitor progress = SubMonitor.convert(monitor, 100);
- *          try {
- *              // Use 30% of the progress to do some work
- *              doSomeWork(progress.split(30));
- *          
- *              // Advance the monitor by another 30%
- *              progress.worked(30);
- *          
- *              // Use the remaining 40% of the progress to do some more work
- *              doSomeWork(progress.split(40));
- *                            
- *          } finally {
- *              SubMonitor.done(monitor);
- *          } 
- *      }
- * </pre>
  * 
  * <p></p>
  * <p><b>Example: Branches</b></p>