docs(content-type): clarify parser selection

moli-content-type/src/lib.rs

@@ -1,20 +1,21 @@
 //! MIME parsing for two distinct browser contexts.
 //!
-//! Choose the entry point from the source of the value:
+//! Choose the entry point from the browser algorithm being implemented:
 //!
 //! - [`parse_mime_type`] applies the WHATWG MIME parsing and serialization
-//!   rules. Use it for standards-facing MIME operations such as Blob/File type
-//!   handling, MIME classification, and interpreting an already selected MIME
-//!   value.
+//!   rules. Use it when a web-platform algorithm says to parse a MIME type,
+//!   including Blob/File type handling, MIME classification and sniffing,
+//!   Fetch response MIME handling, and media capability checks.
 //! - [`parse_response_content_type`] matches Chromium's network-layer parsing
-//!   of a raw HTTP response `Content-Type` field. Use it when transport
-//!   metadata must retain Chromium behavior for values such as `charset` and
-//!   multipart `boundary`.
+//!   of an HTTP response `Content-Type` field. Use it only when reproducing
+//!   Chromium transport-metadata behavior, such as selecting a response
+//!   `charset` or multipart `boundary`.
 //!
 //! These parsers intentionally have different validity and recovery rules. A
-//! value accepted by one is not necessarily accepted by the other, so callers
-//! must select the parser from the value's origin rather than treating the two
-//! result types as interchangeable.
+//! response header can legitimately reach either parser depending on the
+//! operation: MIME classification uses [`parse_mime_type`], while transport
+//! charset selection uses [`parse_response_content_type`]. The result types
+//! are therefore not interchangeable.
 
 mod response;
 mod whatwg;

moli-content-type/src/response.rs

@@ -40,9 +40,10 @@ impl ResponseContentType {
 ///
 /// This intentionally accepts malformed values seen on the network, including
 /// an unterminated quoted parameter and an empty subtype. Use this only for
-/// response transport metadata, such as extracting `charset` or multipart
-/// `boundary`; standards-facing MIME operations must use
-/// [`crate::parse_mime_type`].
+/// Chromium transport-metadata behavior, such as selecting a response
+/// `charset` or multipart `boundary`. A value does not belong here merely
+/// because it came from a response header: web-platform MIME classification
+/// and sniffing use [`crate::parse_mime_type`].
 pub fn parse_response_content_type(input: &str) -> Option<ResponseContentType> {
     // Chromium treats an exact bare wildcard as meaningless, while retaining
     // wildcard values that have parameters or even trailing whitespace.

moli-content-type/src/whatwg.rs

@@ -47,10 +47,10 @@ impl fmt::Display for MimeType {
 /// Parses a standards-facing MIME value using WHATWG validation,
 /// normalization, and parameter recovery rules.
 ///
-/// Use this for Web API MIME operations and for interpreting an already
-/// selected MIME value. Raw HTTP response `Content-Type` metadata must instead
-/// use [`crate::parse_response_content_type`] so its Chromium network behavior
-/// is preserved.
+/// Use this whenever a web-platform algorithm says to parse a MIME type. That
+/// includes MIME classification and sniffing even when the input originated
+/// in an HTTP response header. Use [`crate::parse_response_content_type`] only
+/// for Chromium's separate transport-metadata interpretation.
 pub fn parse_mime_type(input: &str) -> Option<MimeType> {
     input.parse().ok().map(|inner| MimeType { inner })
 }