Merge pull request #424 from sharwell/fix-421

Fix 421

Author: sharwell

src/Documentation/Content/AsynchronousServices.aml

@@ -8,10 +8,21 @@
       <para>
         The openstack.net SDK is migrating to an asynchronous service model using the <token>TaskBasedAsync</token>
         for ongoing feature support. This page contains information about several aspects of the asynchronous interfaces
-        which could result in some confusion during development. It also describes the inclusion of extension methods
-        that allow new product features to be used in code that is not allowed to make asynchronous API
-        calls.
+        which could result in some confusion during development.
       </para>
+      <para>
+        Users unfamiliar with asynchronous programming may find the following introduction particularly valuable.
+      </para>
+      <list class="bullet">
+        <listItem>
+          <para>
+            <externalLink>
+              <linkText>Async and Await</linkText>
+              <linkUri>http://blog.stephencleary.com/2012/02/async-and-await.html</linkUri>
+            </externalLink>
+          </para>
+        </listItem>
+      </list>
     </introduction>
 
     <section address="LanguageSupport">
@@ -194,6 +205,14 @@
           execution of the task itself. The documentation for asynchronous methods does not distinguish between these
           two cases, allowing for any of the specified exceptions to be thrown in either manner.
         </para>
+        <alert class="important">
+          <para>
+            This documentation uses the term asynchronous method to refer to any method with a return type of
+            <codeEntityReference>T:System.Threading.Tasks.Task</codeEntityReference> or
+            <codeEntityReference>T:System.Threading.Tasks.Task`1</codeEntityReference>. Languages with built-in support
+            for asynchronous programming have their own related terminology which may differ in meaning.
+          </para>
+        </alert>
       </content>
 
       <sections>
@@ -231,14 +250,17 @@
             <para>
               This library additionally ensures that exceptions thrown by asynchronous operations are not wrapped in
               multiple layers of <codeEntityReference>T:System.AggregateException</codeEntityReference>. In other words,
-              an <codeEntityReference>T:System.AggregateException</codeEntityReference> thrown during the asynchronous
+              an <codeEntityReference>T:System.ArgumentException</codeEntityReference> thrown during the asynchronous
               execution of a task will result in the
               <codeEntityReference>P:System.Threading.Tasks.Task.Exception</codeEntityReference> property returning an
-              <codeEntityReference>T:System.AggregateException</codeEntityReference> with exactly one inner exception,
-              which is the original <codeEntityReference>T:System.ArgumentException</codeEntityReference>. This
-              guarantee simplifies the use of the API is languages that support <token>AsyncAwait</token>, since those
-              operators automatically unwrap the first layer of
-              <codeEntityReference>T:System.AggregateException</codeEntityReference>.
+              <codeEntityReference>T:System.AggregateException</codeEntityReference>, and that exception will not
+              contain an nested instances of <codeEntityReference>T:System.AggregateException</codeEntityReference> in
+              the <codeEntityReference>P:System.AggregateException.InnerExceptions</codeEntityReference> collection. In
+              most cases, the <codeEntityReference>T:System.AggregateException</codeEntityReference> wraps exactly one
+              inner exception, which is the original
+              <codeEntityReference>T:System.ArgumentException</codeEntityReference>. This guarantee simplifies the use
+              of the API is languages that support <token>AsyncAwait</token>, since those operators automatically unwrap
+              the first layer of <codeEntityReference>T:System.AggregateException</codeEntityReference>.
             </para>
             <code language="cs" region="ExceptionDuringTaskExecution" source="..\Samples\CSharpCodeSamples\AsynchronousExceptionsExamples.cs"/>
             <code language="vb" region="ExceptionDuringTaskExecution" source="..\Samples\VBCodeSamples\AsynchronousExceptionsExamples.vb"/>

src/Samples/CSharpCodeSamples/AsynchronousExceptionsExamples.cs

@@ -15,8 +15,8 @@ public void ExceptionPriorToTaskCreation()
             }
             catch (ArgumentException ex)
             {
-                // ex was thrown directly by SomeOperationAsync. If SomeOperationAsync is marked with the `async`
-                // keyword, then ex was thrown prior to the first use of the `await` keyword within the implementation.
+                // ex was thrown directly by SomeOperationAsync. This cannot occur if SomeOperationAsync is an async
+                // function (§10.15 - C# Language Specification Version 5.0).
             }
             #endregion
         }
@@ -35,9 +35,8 @@ public void ExceptionDuringTaskExecution()
                 if (ex == null)
                     throw;
 
-                // ex was thrown during the asynchronous portion of SomeOperationAsync. If SomeOperationAsync is marked
-                // with the `async` keyword, then ex was thrown after the first use of the `await` keyword within the
-                // method.
+                // ex was thrown during the asynchronous portion of SomeOperationAsync. This is always the case if
+                // SomeOperationAsync is an async function (§10.15 - C# Language Specification Version 5.0).
             }
             #endregion
         }

src/Samples/VBCodeSamples/AsynchronousExceptionsExamples.vb

@@ -8,8 +8,8 @@ Public Class AsynchronousExceptionsExamples
         Try
             Dim myTask As Task = SomeOperationAsync()
         Catch ex As ArgumentException
-            ' ex was thrown directly by SomeOperationAsync. If SomeOperationAsync Is marked with the `Async`
-            ' keyword, then ex was thrown prior to the first use of the `Await` keyword within the implementation.
+            ' ex was thrown directly by SomeOperationAsync. This cannot occur if SomeOperationAsync is an async method
+            ' (§10.1.3 - Visual Basic Language Specification Version 11.0).
         End Try
         ' #End Region
     End Sub
@@ -25,9 +25,8 @@ Public Class AsynchronousExceptionsExamples
                 Throw
             End If
 
-            ' ex was thrown during the asynchronous portion of SomeOperationAsync. If SomeOperationAsync Is marked
-            ' with the `Async` keyword, then ex was thrown after the first use of the `Await` keyword within the
-            ' method.
+            ' ex was thrown during the asynchronous portion of SomeOperationAsync. This is always the case if
+            ' SomeOperationAsync is an async method (§10.1.3 - Visual Basic Language Specification Version 11.0).
         End Try
         ' #End Region
     End Sub