[path_provider] Document null vs UnsupportedError return semantics (#11793) Updates the dartdoc for `getDownloadsDirectory` in `path_provider` and the matching `getDownloadsPath` contract on `PathProviderPlatform` to explain both return-value cases: - `null` — the platform supports the concept of a downloads directory but no such directory is currently available (concrete example: Linux without `xdg-user-dir` installed, or where `xdg-user-dir` fails when called). - `UnsupportedError` — the current platform has no concept of a downloads directory at all. Previously the dartdoc only mentioned the `UnsupportedError` case, which left users unsure when they might see a `null` result. The wording matches the explanations already given by maintainers in the linked issue thread. Fixes flutter/flutter#143238 ## Pre-Review Checklist This is a documentation-only change to public dartdoc comments. No code behavior changes; no new tests are required per the auto-exempt rules for changes that only affect comments/documentation.

diff --git a/packages/path_provider/path_provider/CHANGELOG.md b/packages/path_provider/path_provider/CHANGELOG.md
index 47f9da7..e1fc065 100644
--- a/packages/path_provider/path_provider/CHANGELOG.md
+++ b/packages/path_provider/path_provider/CHANGELOG.md

@@ -1,10 +1,12 @@
-## NEXT
+## 2.1.6
 
 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
 * Updates README to reflect currently supported OS versions for the latest
   versions of the endorsed platform implementations.
   * Applications built with older versions of Flutter will continue to
     use compatible versions of the platform implementations.
+* Documents the difference between a `null` return and an `UnsupportedError`
+  from `getDownloadsDirectory`.
 
 ## 2.1.5
 

diff --git a/packages/path_provider/path_provider/lib/path_provider.dart b/packages/path_provider/path_provider/lib/path_provider.dart
index 2883d04..92051eb 100644
--- a/packages/path_provider/path_provider/lib/path_provider.dart
+++ b/packages/path_provider/path_provider/lib/path_provider.dart

@@ -207,8 +207,13 @@
 /// The returned directory is not guaranteed to exist, so clients should verify
 /// that it does before using it, and potentially create it if necessary.
 ///
-/// Throws an [UnsupportedError] if this is not supported on the current
-/// platform.
+/// Returns `null` when the current platform supports the concept of a
+/// downloads directory but no such directory is currently available. For
+/// example, on Linux this can happen when `xdg-user-dir` is not installed
+/// or fails when called.
+///
+/// Throws an [UnsupportedError] when the current platform has no concept of
+/// a downloads directory at all.
 Future<Directory?> getDownloadsDirectory() async {
   final String? path = await _platform.getDownloadsPath();
   if (path == null) {

diff --git a/packages/path_provider/path_provider/pubspec.yaml b/packages/path_provider/path_provider/pubspec.yaml
index bb3acf4..92b660e 100644
--- a/packages/path_provider/path_provider/pubspec.yaml
+++ b/packages/path_provider/path_provider/pubspec.yaml

@@ -2,7 +2,7 @@
 description: Flutter plugin for getting commonly used locations on host platform file systems, such as the temp and app data directories.
 repository: https://github.com/flutter/packages/tree/main/packages/path_provider/path_provider
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22
-version: 2.1.5
+version: 2.1.6
 
 environment:
   sdk: ^3.10.0

diff --git a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md
index f7c254e..08cc4c8 100644
--- a/packages/path_provider/path_provider_platform_interface/CHANGELOG.md
+++ b/packages/path_provider/path_provider_platform_interface/CHANGELOG.md

@@ -1,6 +1,8 @@
-## NEXT
+## 2.1.3
 
 * Updates minimum supported SDK version to Flutter 3.38/Dart 3.10.
+* Documents the implementation contract for `null` versus `UnsupportedError`
+  return semantics on `getDownloadsPath`.
 
 ## 2.1.2
 

diff --git a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart
index ba2bba4..f85caf5 100644
--- a/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart
+++ b/packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart

@@ -93,6 +93,14 @@
 
   /// Path to the directory where downloaded files can be stored.
   /// This is typically only relevant on desktop operating systems.
+  ///
+  /// Implementations should return `null` when the platform supports the
+  /// concept of a downloads directory but no such directory is currently
+  /// available (for example, on Linux when `xdg-user-dir` is not installed
+  /// or fails when called).
+  ///
+  /// Implementations should throw an [UnsupportedError] when the platform
+  /// has no concept of a downloads directory at all.
   Future<String?> getDownloadsPath() {
     throw UnimplementedError('getDownloadsPath() has not been implemented.');
   }

diff --git a/packages/path_provider/path_provider_platform_interface/pubspec.yaml b/packages/path_provider/path_provider_platform_interface/pubspec.yaml
index 37dd1c7..d65d8fe 100644
--- a/packages/path_provider/path_provider_platform_interface/pubspec.yaml
+++ b/packages/path_provider/path_provider_platform_interface/pubspec.yaml

@@ -4,7 +4,7 @@
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+path_provider%22
 # NOTE: We strongly prefer non-breaking changes, even at the expense of a
 # less-clean API. See https://flutter.dev/go/platform-interface-breaking-changes
-version: 2.1.2
+version: 2.1.3
 
 environment:
   sdk: ^3.10.0