From 1fb79097c93093d778a2f4709b5365c206873fd1 Mon Sep 17 00:00:00 2001
From: Andrew Arnott <andrew.arnott@microsoft.com>
Date: Wed, 28 Jun 2023 09:27:29 -0600
Subject: [PATCH] Update and restructure README

---
 README.md                                     | 63 ++++++-------------
 .../README.md                                 |  5 ++
 .../README.md                                 | 28 +++++++++
 3 files changed, 53 insertions(+), 43 deletions(-)
 create mode 100644 src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/README.md
 create mode 100644 src/Microsoft.VisualStudio.Threading/README.md

diff --git a/README.md b/README.md
index d1e841e86..ba08fea4f 100644
--- a/README.md
+++ b/README.md
@@ -1,47 +1,24 @@
-Microsoft.VisualStudio.Threading
-=================================
+# vs-threading
 
-[![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Threading.svg)](https://nuget.org/packages/Microsoft.VisualStudio.Threading)
 [![Build Status](https://dev.azure.com/azure-public/vside/_apis/build/status/vs-threading)](https://dev.azure.com/azure-public/vside/_build/latest?definitionId=12)
 [![Join the chat at https://gitter.im/vs-threading/Lobby](https://badges.gitter.im/vs-threading/Lobby.svg)](https://gitter.im/vs-threading/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
-Analyzers: [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Threading.Analyzers.svg)](https://nuget.org/packages/Microsoft.VisualStudio.Threading.Analyzers)
-
-## Features
-
-* Async versions of many threading synchronization primitives
-  * `AsyncAutoResetEvent`
-  * `AsyncBarrier`
-  * `AsyncCountdownEvent`
-  * `AsyncManualResetEvent`
-  * `AsyncReaderWriterLock`
-  * `AsyncSemaphore`
-  * `ReentrantSemaphore`
-* Async versions of very common types
-  * `AsyncEventHandler`
-  * `AsyncLazy<T>`
-  * `AsyncLazyInitializer`
-  * `AsyncLocal<T>`
-  * `AsyncQueue<T>`
-* Await extension methods
-  * Await on a `TaskScheduler` to switch to it.
-    Switch to a background thread with `await TaskScheduler.Default;`
-  * Await on a `Task` with a timeout
-  * Await on a `Task` with cancellation
-* `JoinableTaskFactory` that allows you to schedule asynchronous or synchronous work
-  that does not deadlock with the UI thread even when the UI thread needs to
-  synchronously block on the result.
-
-## Documentation
-
-* [Overview documentation](doc/index.md)
-* [Diagnostic analyzer rules](doc/analyzers/index.md)
-
-## Supported platforms
-
-* .NET 4.5
-* .NET 4.6
-* .NET Standard 1.3
-* .NET Standard 2.0
-
-[1]: https://nuget.org/packages/Microsoft.VisualStudio.Threading "Microsoft.VisualStudio.Threading NuGet package"
+## Microsoft.VisualStudio.Threading
+
+[![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Threading.svg)](https://nuget.org/packages/Microsoft.VisualStudio.Threading)
+
+Async synchronization primitives, async collections, TPL and dataflow extensions. The JoinableTaskFactory allows synchronously blocking the UI thread for async work. This package is applicable to any .NET application (not just Visual Studio).
+
+[Overview documentation](doc/index.md).
+
+[See the full list of features](src/Microsoft.VisualStudio.Threading/README.md).
+
+## Microsoft.VisualStudio.Threading.Analyzers
+
+[![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Threading.Analyzers.svg)](https://nuget.org/packages/Microsoft.VisualStudio.Threading.Analyzers)
+
+Static code analyzer to detect common mistakes or potential issues regarding threading and async coding.
+
+[Diagnostic analyzer rules](doc/analyzers/index.md).
+
+[See the full list of features](src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/README.md).
diff --git a/src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/README.md b/src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/README.md
new file mode 100644
index 000000000..b6955d52e
--- /dev/null
+++ b/src/Microsoft.VisualStudio.Threading.Analyzers.CodeFixes/README.md
@@ -0,0 +1,5 @@
+# Microsoft.VisualStudio.Threading.Analyzers
+
+Static code analyzers to detect common mistakes or potential issues regarding threading and async coding.
+
+[Diagnostic analyzer rules](https://github.com/microsoft/vs-threading/blob/main/doc/analyzers/index.md).
diff --git a/src/Microsoft.VisualStudio.Threading/README.md b/src/Microsoft.VisualStudio.Threading/README.md
new file mode 100644
index 000000000..465ce9f1d
--- /dev/null
+++ b/src/Microsoft.VisualStudio.Threading/README.md
@@ -0,0 +1,28 @@
+# Microsoft.VisualStudio.Threading
+
+Async synchronization primitives, async collections, TPL and dataflow extensions. The JoinableTaskFactory allows synchronously blocking the UI thread for async work. This package is applicable to any .NET application (not just Visual Studio).
+
+## Features
+
+* Async versions of many threading synchronization primitives
+  * `AsyncAutoResetEvent`
+  * `AsyncBarrier`
+  * `AsyncCountdownEvent`
+  * `AsyncManualResetEvent`
+  * `AsyncReaderWriterLock`
+  * `AsyncSemaphore`
+  * `ReentrantSemaphore`
+* Async versions of very common types
+  * `AsyncEventHandler`
+  * `AsyncLazy<T>`
+  * `AsyncLazyInitializer`
+  * `AsyncLocal<T>`
+  * `AsyncQueue<T>`
+* Await extension methods
+  * Await on a `TaskScheduler` to switch to it.
+    Switch to a background thread with `await TaskScheduler.Default;`
+  * Await on a `Task` with a timeout
+  * Await on a `Task` with cancellation
+* `JoinableTaskFactory` that allows you to schedule asynchronous or synchronous work
+  that does not deadlock with the UI thread even when the UI thread needs to
+  synchronously block on the result.