[path_provider] Document null vs UnsupportedError return semantics

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
 

packages/path_provider/path_provider/lib/path_provider.dart

@@ -217,8 +217,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) {

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

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
 

packages/path_provider/path_provider_platform_interface/lib/path_provider_platform_interface.dart

@@ -105,6 +105,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.');
   }

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