[path_provider] Document null vs UnsupportedError return semantics (#11793)

theprantadutta · web-flow · commit aa964a3ed6d9 · 2026-06-15T13:34:12.000Z
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
@@ -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
@@ -207,8 +207,13 @@ Future<List<Directory>?> getExternalStorageDirectories({
 /// 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
@@ -2,7 +2,7 @@ name: path_provider
 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
@@ -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
@@ -93,6 +93,14 @@ abstract class PathProviderPlatform extends PlatformInterface {
 
   /// 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
@@ -4,7 +4,7 @@ repository: https://github.com/flutter/packages/tree/main/packages/path_provider
 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
