Merge pull request #1332 from AArnott/documentThrowingBehaviors

Document Join APIs that may propagate exceptions

Author: AArnott

src/Microsoft.VisualStudio.Threading/JoinableTask.cs

@@ -568,6 +568,10 @@ private Task QueueNeedProcessEvent
     /// the caller's access to the Main thread propagates to this JoinableTask so that it may also access the main thread.
     /// </summary>
     /// <param name="cancellationToken">A cancellation token that will exit this method before the task is completed.</param>
+    /// <exception cref="OperationCanceledException">Thrown when <paramref name="cancellationToken"/> is canceled.</exception>
+    /// <remarks>
+    /// Any exception thrown by the asynchronous operation is propagated out to the caller of this method.
+    /// </remarks>
     public void Join(CancellationToken cancellationToken = default(CancellationToken))
     {
         cancellationToken.ThrowIfCancellationRequested();
@@ -599,6 +603,10 @@ private Task QueueNeedProcessEvent
     /// before the async operation has completed.
     /// </param>
     /// <returns>A task that completes after the asynchronous operation completes and the join is reverted.</returns>
+    /// <exception cref="OperationCanceledException">Thrown when <paramref name="cancellationToken"/> is canceled.</exception>
+    /// <remarks>
+    /// Any exception thrown by the asynchronous operation is propagated out to the caller of this method.
+    /// </remarks>
     public Task JoinAsync(CancellationToken cancellationToken = default(CancellationToken))
     {
         cancellationToken.ThrowIfCancellationRequested();

src/Microsoft.VisualStudio.Threading/JoinableTaskCollection.cs

@@ -145,13 +145,19 @@ public JoinRelease Join()
     /// Joins the caller's context to this collection till the collection is empty.
     /// </summary>
     /// <returns>A task that completes when this collection is empty.</returns>
+    /// <remarks>
+    /// Any exceptions thrown by the tasks in this collection are <em>not</em> propagated to the returned task.
+    /// </remarks>
     public Task JoinTillEmptyAsync() => this.JoinTillEmptyAsync(CancellationToken.None);
 
     /// <summary>
     /// Joins the caller's context to this collection till the collection is empty.
     /// </summary>
     /// <param name="cancellationToken">A cancellation token.</param>
     /// <returns>A task that completes when this collection is empty, or is canceled when <paramref name="cancellationToken"/> is canceled.</returns>
+    /// <remarks>
+    /// Any exceptions thrown by the tasks in this collection are <em>not</em> propagated to the returned task.
+    /// </remarks>
     public async Task JoinTillEmptyAsync(CancellationToken cancellationToken)
     {
         cancellationToken.ThrowIfCancellationRequested();

src/Microsoft.VisualStudio.Threading/JoinableTask`1.cs

@@ -48,6 +48,10 @@ internal JoinableTask(JoinableTaskFactory owner, bool synchronouslyBlocking, str
         /// </summary>
         /// <param name="cancellationToken">A cancellation token that will exit this method before the task is completed.</param>
         /// <returns>A task that completes after the asynchronous operation completes and the join is reverted, with the result of the operation.</returns>
+        /// <exception cref="OperationCanceledException">Thrown when <paramref name="cancellationToken"/> is canceled.</exception>
+        /// <remarks>
+        /// Any exception thrown by the asynchronous operation is propagated out to the caller of this method.
+        /// </remarks>
         public new Task<T> JoinAsync(CancellationToken cancellationToken = default(CancellationToken))
         {
             return this.JoinAsync(continueOnCapturedContext: AwaitShouldCaptureSyncContext, cancellationToken);
@@ -59,6 +63,10 @@ internal JoinableTask(JoinableTaskFactory owner, bool synchronouslyBlocking, str
         /// </summary>
         /// <param name="cancellationToken">A cancellation token that will exit this method before the task is completed.</param>
         /// <returns>The result of the asynchronous operation.</returns>
+        /// <exception cref="OperationCanceledException">Thrown when <paramref name="cancellationToken"/> is canceled.</exception>
+        /// <remarks>
+        /// Any exception thrown by the asynchronous operation is propagated out to the caller of this method.
+        /// </remarks>
         public new T Join(CancellationToken cancellationToken = default(CancellationToken))
         {
             base.Join(cancellationToken);