From edad6d8a9b5ce91f6be85c71396d8e1d2acd1032 Mon Sep 17 00:00:00 2001 From: Si Beaumont Date: Fri, 6 Feb 2026 18:56:42 +0000 Subject: [PATCH] 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 | 2 +- README.md | 4 ++-- Sources/NIO/Docs.docc/index.md | 4 ++-- Sources/NIOFileSystem/Docs.docc/index.md | 13 +++++++++++++ 4 files changed, 18 insertions(+), 5 deletions(-) create mode 100644 Sources/NIOFileSystem/Docs.docc/index.md diff --git a/.spi.yml b/.spi.yml index b7e67f93a..411777da5 100644 --- a/.spi.yml +++ b/.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] diff --git a/README.md b/README.md index 64da5c1a8..bae535f41 100644 --- a/README.md +++ b/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 diff --git a/Sources/NIO/Docs.docc/index.md b/Sources/NIO/Docs.docc/index.md index 5532fda0b..5e04a66de 100644 --- a/Sources/NIO/Docs.docc/index.md +++ b/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 diff --git a/Sources/NIOFileSystem/Docs.docc/index.md b/Sources/NIOFileSystem/Docs.docc/index.md new file mode 100644 index 000000000..62e7a7a74 --- /dev/null +++ b/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