Bug 515780 - Minor updates to the progress monitor article

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

1 files changed, 31 insertions, 3 deletions

diff --git a/Article-Progress-Monitors/article.html b/Article-Progress-Monitors/article.html
index 53231d4..92f8b10 100644
--- a/Article-Progress-Monitors/article.html
+++ b/Article-Progress-Monitors/article.html
@@ -196,7 +196,7 @@ additionally includes a cancellation check. Internally, split does something lik
 
 <p>
 In some rare cases, you really need to perform an explicit cancellation check
-at a specific time and can't rely on the intermittent cancellation checks done
+at a specific time and can't rely on the sparse cancellation checks done
 by <code>split</code>. In such cases, you can use the <code>SubMonitor.checkCanceled</code>
 utility introduced in Eclipse 4.7.
 <p>
@@ -222,7 +222,7 @@ the API contracts on a SubMonitor. The tracing options can also be enabled in th
 <i>tracing</i> tab of any launch configuration. If you maintain any code that reports
 progress, it's generally a good idea to leave these options enabled at all times.
 <p>
-If you see nothing it either means that your code is working perfectly or that the
+If you see nothing, it either means that your code is working perfectly or that the
 diagnostic tool isn't running. You can confirm that the diagnostic tool is running by
 using your debugger to confirm that the following variable is true:
 
@@ -430,7 +430,35 @@ long it will take? Try allocating a small percentage of the remaining space on e
 Notice the idiom <code>setWorkRemaining(denominator).split(numerator)</code>. This can be used
 at any point to consume numerator/denominator of the remaining space in a monitor. 
 
-<h3>3.7 Naming conventions</h3>
+<h3>3.7 Try / catch / finally blocks</h3>
+
+What if you need to do something in a catch or finally block that reports progress?
+This is tricky since catch and finally blocks should almost never perform cancellation checks.
+Otherwise, they're likely to throw an <code>OperationCanceledException</code> while running the very
+code that reacts to <code>OperationCanceledException</code>. For this reason, you should use the
+<code>SUPPRESS_ISCANCELED</code> flag whenever creating a child monitor within a catch or finally
+block.
+
+<pre>
+    void tryFinallyBlockExample(IProgressMonitor monitor) {
+        SubMonitor subMonitor = SubMonitor.convert(monitor, 2);
+        try {
+            doOperation(subMonitor.split(1));
+        } catch (SomeException e) {
+            handleException(subMonitor.setWorkRemaining(2)
+                .split(1, SubMonitor.SUPPRESS_ISCANCELED | SubMonitor.SUPPRESS_BEGINTASK));
+        } finally {
+            doFinallyBlock(subMonitor
+                .split(1, SubMonitor.SUPPRESS_ISCANCELED | SubMonitor.SUPPRESS_BEGINTASK));
+        }
+    }
+</pre>
+
+Notice that this example also uses the <code>SUPPRESS_BEGINTASK</code> flag. When passing flags to
+<code>split</code> or <code>newChild</code>, you should always include the
+<code>SUPPRESS_BEGINTASK</code> flag unless you have a specific reason not to. 
+
+<h3>3.8 Naming conventions</h3>
 
 In these examples we've used the same naming convention that has been used within
 the Eclipse platform. You may wish to use the same convention to help convey the purpose of your