From 03f83a48a4753e51f2f97922fc3d5a30390c8942 Mon Sep 17 00:00:00 2001
From: Andrew Arnott <andrewarnott@gmail.com>
Date: Mon, 19 Feb 2018 02:22:04 -0800
Subject: [PATCH] Update docs

---
 doc/analyzers/VSTHRD010.md                    | 25 ++++++++++++++++---
 .../VSTHRD010MainThreadUsageAnalyzer.cs       |  9 +++----
 2 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/doc/analyzers/VSTHRD010.md b/doc/analyzers/VSTHRD010.md
index 6baf3432..526f1c57 100644
--- a/doc/analyzers/VSTHRD010.md
+++ b/doc/analyzers/VSTHRD010.md
@@ -1,10 +1,19 @@
 # VSTHRD010 Invoke single-threaded types on Main thread
 
-Acquiring, casting, or invoking Visual Studio services should be done after ensuring
-that your code is running on the UI thread.
+Acquiring, casting, or invoking single-threaded objects should be done after ensuring
+that your code is running on the main thread.
+
+This analyzer can be configured to:
+1. Recognize the objects that are single-threaded that are unique to your app or library.   
+2. Recognize synchronous methods that verify the caller is already on the main thread.
+3. Recognize methods that switch to the main thread when the caller awaits them.
+   Calls to `JoinableTaskFactory.SwitchToMainThreadAsync` methods are pre-configured.
 
 ## Examples of patterns that are flagged by this analyzer
 
+This example is based on the configuration available from the Visual Studio SDK
+that defines `IVs*` interfaces as requiring the main thread.
+
 ```csharp
 private void CallVS()
 {
@@ -15,9 +24,13 @@ private void CallVS()
 
 ## Solution
 
-First ensure you are running on the UI thread before interacting with a Visual Studio service.
+First ensure you are running on the main thread before interacting with single-threaded objects.
 Either throw when you are not on the appropriate thread, or explicitly switch to the 
-UI thread.
+main thread.
+
+This solution example is based on the configuration available from the Visual Studio SDK
+that defines `ThreadHelper.ThrowIfNotOnUIThread()` as one which throws if the caller
+is not already on the main thread.
 
 ```csharp
 private void CallVS()
@@ -36,3 +49,7 @@ private async Task CallVSAsync()
 ```
 
 Refer to [Asynchronous and multithreaded programming within VS using the JoinableTaskFactory](http://blogs.msdn.com/b/andrewarnottms/archive/2014/05/07/asynchronous-and-multithreaded-programming-within-vs-using-the-joinabletaskfactory/) for more info.
+
+## Configuration
+
+TODO
diff --git a/src/Microsoft.VisualStudio.Threading.Analyzers/VSTHRD010MainThreadUsageAnalyzer.cs b/src/Microsoft.VisualStudio.Threading.Analyzers/VSTHRD010MainThreadUsageAnalyzer.cs
index 885af07d..cb4999c4 100644
--- a/src/Microsoft.VisualStudio.Threading.Analyzers/VSTHRD010MainThreadUsageAnalyzer.cs
+++ b/src/Microsoft.VisualStudio.Threading.Analyzers/VSTHRD010MainThreadUsageAnalyzer.cs
@@ -3,21 +3,18 @@
     using System;
     using System.Collections.Generic;
     using System.Collections.Immutable;
-    using System.IO;
     using System.Linq;
-    using System.Text.RegularExpressions;
     using System.Threading;
     using Microsoft.CodeAnalysis;
     using Microsoft.CodeAnalysis.CSharp;
     using Microsoft.CodeAnalysis.CSharp.Syntax;
     using Microsoft.CodeAnalysis.Diagnostics;
-    using Microsoft.CodeAnalysis.Text;
-    using Microsoft.VisualStudio.Shell;
     using Microsoft.VisualStudio.Threading;
 
     /// <summary>
-    /// Report warnings when detect the usage on Visual Studio services (i.e. IVsSolution) without verified
-    /// that the current thread is main thread, or switched to main thread prior invocation explicitly.
+    /// Flag usage of objects that must only be invoked while on the main thread (e.g. STA COM objects)
+    /// without having first verified that the current thread is main thread either by throwing if on
+    /// the wrong thread or asynchronously switching to the main thread.
     /// </summary>
     /// <remarks>
     /// [Background] Most of Visual Studio services especially the legacy services which are implemented in native code