Clarify cross_file MIME type docs

[mackings]

Clarifies the cross_file documentation for XFile.mimeType.

This PR documents that mimeType is not inferred from the file path or file contents. It is only available when provided while creating the XFile, or when available from the platform-backed file.

Fixes flutter/flutter#93379

Pre-Review Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the AI contribution guidelines and understand my responsibilities, or I am not using AI tools.
• I read the Tree Hygiene page, which explains my responsibilities.
• I read and followed the relevant style guides and ran the auto-formatter.
• I signed the CLA.
• The title of the PR starts with the name of the package surrounded by square brackets, e.g. [shared_preferences]
• I linked to at least one issue that this PR fixes in the description above.
• I followed the version and CHANGELOG instructions, using semantic versioning and the repository CHANGELOG style, or I have commented below to indicate which documented exception this PR falls under¹.
• I updated/added any relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or I have commented below to indicate which test exemption this PR falls under¹.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful, you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Footnotes

1. Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

[gemini-code-assist]

Code Review

This pull request updates the documentation for XFile to clarify that the mimeType property is not automatically inferred from file paths or contents. These updates are reflected in the CHANGELOG.md, README.md, and the base and IO implementations of XFile. Feedback was provided to improve the clarity of the documentation in the XFile constructors by explicitly stating that the mimeType is only available if passed to the constructor, and to ensure consistency by applying similar updates to the HTML implementation.

[gemini-code-assist]

The phrasing "returned from [mimeType]" is confusing because [mimeType] is used for both the parameter and the property in this context. It would be clearer to state that the property is only available if the parameter is provided. Additionally, for consistency, please consider applying similar documentation updates to the XFile constructors in lib/src/types/html.dart.

Suggested change

	/// [mimeType] is not inferred from [path] and is returned from [mimeType]
	/// only if explicitly passed.
	/// [mimeType] is not inferred from [path] and is only available if explicitly
	/// passed to the constructor.

[mackings]

I updated the wording in io.dart and added matching constructor documentation in html.dart. Tests still pass.

[gemini-code-assist]

The phrasing "returned from [mimeType]" is redundant. It's clearer to specify that the value is only available if provided during construction.

Suggested change

	/// [mimeType] is returned from [mimeType] only if explicitly passed.
	/// [mimeType] is only available if explicitly passed to the constructor.

[stuartmorgan-g]

Thanks for the contribution! You’ve checked boxes in the PR checklist above that are not reflected in this PR, so I’m assuming this is a work in progress and am marking it as a Draft. Please review the checklist, updating the PR as appropriate, and when the state of the PR as posted reflects the checklist please feel free to mark it as ready for review.