[cross_file] Document mime type is not made for io implementations

packages/cross_file/CHANGELOG.md

@@ -1,6 +1,8 @@
-## NEXT
+## 0.3.4+5
 
 * Updates minimum supported SDK version to Flutter 3.3/Dart 2.18.
+* Improved documentation about ignored parameters in IO module.=======
+
 
 ## 0.3.3+4
 

packages/cross_file/lib/src/types/base.dart

@@ -44,6 +44,8 @@ abstract class XFileBase {
   }
 
   /// For web, it may be necessary for a file to know its MIME type.
+  ///
+  /// For io implementation, this is not intended to be set and will be `null`.
   String? get mimeType {
     throw UnimplementedError('.mimeType has not been implemented.');
   }

packages/cross_file/lib/src/types/io.dart

@@ -17,6 +17,15 @@ class XFile extends XFileBase {
   /// [bytes] is ignored; the parameter exists only to match the web version of
   /// the constructor. To construct a dart:io XFile from bytes, use
   /// [XFile.fromData].
+  ///
+  /// [name] is ignored; the parameter exists only to match the web version of
+  /// the constructor. **You should avoid using this parameter because it will
+  /// be likely removed in the future releases.**
+  ///
+  /// [length] is ignored; the parameter exists only to match the web version of
+  /// the constructor. **You should avoid using this parameter because it will
+  /// be likely removed in the future releases.**
+  ///
   // ignore: use_super_parameters
   XFile(
     String path, {
@@ -32,6 +41,10 @@ class XFile extends XFileBase {
         super(path);
 
   /// Construct an CrossFile from its data
+  ///
+  /// [name] is ignored; the parameter exists only to match the web version of
+  /// the constructor. **You should avoid using this parameter because it will
+  /// be likely removed in the future releases.**
   XFile.fromData(
     Uint8List bytes, {
     String? mimeType,
@@ -82,9 +95,17 @@ class XFile extends XFileBase {
   @override
   String get path => _file.path;
 
+  /// the name extracted from the last part of [File.path].
+  ///
+  /// **Be aware**, the name here is not the one
+  /// you may have passed in the constructor/factory.
   @override
   String get name => _file.path.split(Platform.pathSeparator).last;
 
+  /// the [File.length].
+  ///
+  /// **Be aware**, the length here is not the one
+  /// you may have passed in the constructor/factory.
   @override
   Future<int> length() {
     if (_length != null) {

packages/cross_file/pubspec.yaml

@@ -2,7 +2,7 @@ name: cross_file
 description: An abstraction to allow working with files across multiple platforms.
 repository: https://github.com/flutter/packages/tree/main/packages/cross_file
 issue_tracker: https://github.com/flutter/flutter/issues?q=is%3Aissue+is%3Aopen+label%3A%22p%3A+cross_file%22
-version: 0.3.3+4
+version: 0.3.4+5
 
 environment:
   sdk: ">=2.18.0 <4.0.0"