Clarify state and relationship of NIOFileSystem and _NIOFileSystem in API docs (#3504)

### Motivation:

`NIOFileSystem` currently exposes the same API as `_NIOFileSystem`,
which is not API stable. `NIOFileSystem`
was created in error, and its lack of underscore incorrectly implies API
stability. Users who are currently importing `NIOFileSystem` should
ideally move to `_NIOFileSystem`. However this isn't made clear in the
docs:

1. The README talks about the non-underscored `NIOFileSystem`.
2. There are no hosted API docs `NIOFileSystem`.
3. The hosted API docs for `NIO` point to the docs for `NIOFileSystem`
-- results in 404.

### Modifications:

- Update the README to refer to `_NIOFileSystem`.
- Update the hosted API docs for `NIO` to point to docs for
`_NIOFileSystem`.
- Add hosted API docs for `NIOFileSystem` with a statement explaining
the situation and pointing people to the docs
  for `_NIOFileSystem`.

### Result:

Clearer documentation on the state and relationship of the
`NIOFileSystem` and `_NIOFileSystem` modules.

.spi.yml

@@ -1,4 +1,4 @@
 version: 1
 builder:
   configs:
-    - documentation_targets: [NIO, NIOConcurrencyHelpers, NIOCore, NIOEmbedded, NIOFoundationCompat, NIOHTTP1, NIOPosix, NIOTLS, NIOWebSocket, NIOTestUtils, _NIOFileSystem]
+    - documentation_targets: [NIO, NIOConcurrencyHelpers, NIOCore, NIOEmbedded, NIOFoundationCompat, NIOHTTP1, NIOPosix, NIOTLS, NIOWebSocket, NIOTestUtils, _NIOFileSystem, NIOFileSystem]

README.md

@@ -32,7 +32,7 @@ Within this repository we have a number of products that provide different funct
 - `NIOHTTP1`. This provides a low-level HTTP/1.1 protocol implementation.
 - `NIOWebSocket`. This provides a low-level WebSocket protocol implementation.
 - `NIOTestUtils`. This provides a number of helpers for testing projects that use SwiftNIO.
-- `NIOFileSystem`. This provides `async` APIs for interacting with the file system.
+- `_NIOFileSystem`. This provides `async` APIs for interacting with the file system.
 
 ### Protocol Implementations
 
@@ -103,7 +103,7 @@ SwiftNIO aims to support all of the platforms where Swift is supported. Currentl
 * Ubuntu 18.04+
 * macOS 10.9+, iOS 7+; (macOS 10.14+, iOS 12+, tvOS 12+ or watchOS 6+ with [swift-nio-transport-services][repo-nio-transport-services])
 
-SwiftNIO has experimental support on OpenBSD for all SwiftNIO libraries _except_ for NIOFileSystem, which is not yet supported. You can use all other SwiftNIO libraries on OpenBSD by adding them as dependencies in `Package.swift`.
+SwiftNIO has experimental support on OpenBSD for all SwiftNIO libraries _except_ for `_NIOFileSystem`, which is not yet supported. You can use all other SwiftNIO libraries on OpenBSD by adding them as dependencies in `Package.swift`.
 
 ### Compatibility
 

Sources/NIO/Docs.docc/index.md

@@ -35,7 +35,7 @@ SwiftNIO has a number of products that provide different functionality. This pac
 - [NIOHTTP1][module-http1]. This provides a low-level HTTP/1.1 protocol implementation.
 - [NIOWebSocket][module-websocket]. This provides a low-level WebSocket protocol implementation.
 - [NIOTestUtils][module-test-utilities]. This provides a number of helpers for testing projects that use SwiftNIO.
-- [NIOFileSystem][module-filesystem]. This provides `async` APIs for interacting with the file system.
+- [_NIOFileSystem][module-filesystem]. This provides `async` APIs for interacting with the file system.
 
 ### Conceptual Overview
 
@@ -168,7 +168,7 @@ The core SwiftNIO repository will contain a few extremely important protocol imp
 [module-tls]: ./NIOTLS
 [module-websocket]: ./NIOWebSocket
 [module-test-utilities]: ./NIOTestUtils
-[module-filesystem]: ./NIOFileSystem
+[module-filesystem]: ./_NIOFileSystem
 
 [ch]: ./NIOCore/ChannelHandler
 [c]: ./NIOCore/Channel

Sources/NIOFileSystem/Docs.docc/index.md

@@ -0,0 +1,13 @@
+# ``NIOFileSystem``
+
+> Warning: Do not use this module. Instead use [`_NIOFileSystem`][_fs-docs].
+>
+> `NIOFileSystem` currently exposes the same API as `_NIOFileSystem`, which is not API stable. `NIOFileSystem`
+> was created in error, and its lack of underscore incorrectly implies API stability. Users who are currently importing
+> `NIOFileSystem` should move to `_NIOFileSystem`.
+>
+> Refer to [`_NIOFilesystem`][_fs-docs] for documentation on the API of this module.
+>
+> There is ongoing work in NIO to provide a filesystem library with a stable API.
+
+[_fs-docs]: ./_NIOFileSystem