[net/base] Document how MIME mappings are used.

Bug: None
Change-Id: I881f20202ff1efaa2655173366f4f9ae5b86cdad
Reviewed-on: https://chromium-review.googlesource.com/c/1300777Reviewed-by: Matt Menke <mmenke@chromium.org>
Commit-Queue: Asanka Herath <asanka@chromium.org>
Cr-Commit-Position: refs/heads/master@{#605126}

net/base/mime_util.cc

@@ -74,8 +74,76 @@ struct MimeInfo {
   const char* const extensions;
 };
 
-// Order of entries in the following mapping lists matters only when the same
-// extension is shared between multiple MIME types.
+// How to use the MIME maps
+// ------------------------
+// READ THIS BEFORE MODIFYING THE MIME MAPPINGS BELOW.
+//
+// There are two hardcoded mappings from MIME types: kPrimaryMappings and
+// kSecondaryMappings.
+//
+// kPrimaryMappings:
+//
+//   Use this for mappings that are critical to the web platform.  Mappings you
+//   add to this list take priority over the underlying platform when converting
+//   from file extension -> MIME type.  Thus file extensions listed here will
+//   work consistently across platforms.
+//
+// kSecondaryMappings:
+//
+//   Use this for mappings that must exist, but can be overridden by user
+//   preferences.
+//
+// The following applies to both lists:
+//
+// * The same extension can appear multiple times in the same list under
+//   different MIME types.  Extensions that appear earlier take precedence over
+//   those that appear later.
+//
+// * A MIME type must not appear more than once in a single list.  It is valid
+//   for the same MIME type to appear in kPrimaryMappings and
+//   kSecondaryMappings.
+//
+// The MIME maps are used for three types of lookups:
+//
+// 1) MIME type -> file extension.  Implemented as
+//    GetPreferredExtensionForMimeType().
+//
+//    Sources are consulted in the following order:
+//
+//    a) As a special case application/octet-stream is mapped to nothing.  Web
+//       sites are supposed to use this MIME type to indicate that the content
+//       is opaque and shouldn't be parsed as any specific type of content.  It
+//       doesn't make sense to map this to anything.
+//
+//    b) The underlying platform.  If the operating system has a mapping from
+//       the MIME type to a file extension, then that takes priority.  The
+//       platform is assumed to represent the user's preference.
+//
+//    c) kPrimaryMappings.  Order doesn't matter since there should only be at
+//       most one entry per MIME type.
+//
+//    d) kSecondaryMappings.  Again, order doesn't matter.
+//
+// 2) File extension -> MIME type.  Implemented in GetMimeTypeFromExtension().
+//
+//    Sources are considered in the following order:
+//
+//    a) kPrimaryMappings.  Order matters here since file extensions can appear
+//       multiple times on these lists.  The first mapping in order of
+//       appearance in the list wins.
+//
+//    b) Underlying platform.
+//
+//    c) kSecondaryMappings.  Again, the order matters.
+//
+// 3) File extension -> Well known MIME type.  Implemented as
+//    GetWellKnownMimeTypeFromExtension().
+//
+//    This is similar to 2), with the exception that b) is skipped.  I.e.  Only
+//    considers the hardcoded mappings in kPrimaryMappings and
+//    kSecondaryMappings.
+
+// See comments above for details on how this list is used.
 static const MimeInfo kPrimaryMappings[] = {
     // Must precede audio/webm .
     {"video/webm", "webm"},
@@ -103,6 +171,7 @@ static const MimeInfo kPrimaryMappings[] = {
     {"video/ogg", "ogv,ogm"},
 };
 
+// See comments above for details on how this list is used.
 static const MimeInfo kSecondaryMappings[] = {
     // Must precede image/vnd.microsoft.icon .
     {"image/x-icon", "ico"},

net/base/mime_util.h

@@ -80,11 +80,12 @@ NET_EXPORT bool ParseMimeTypeWithoutParameter(const std::string& type_string,
 // this method.
 NET_EXPORT bool IsValidTopLevelMimeType(const std::string& type_string);
 
-// Get the extensions associated with the given mime type. There could be
-// multiple extensions for a given mime type, like "html,htm" for "text/html",
-// or "txt,text,html,..." for "text/*".
-// Note that we do not erase the existing elements in the the provided vector.
-// Instead, we append the result to it.
+// Get the extensions associated with the given mime type.
+//
+// There could be multiple extensions for a given mime type, like "html,htm" for
+// "text/html", or "txt,text,html,..." for "text/*".  Note that we do not erase
+// the existing elements in the the provided vector.  Instead, we append the
+// result to it.  The new extensions are returned in no particular order.
 NET_EXPORT void GetExtensionsForMimeType(
     const std::string& mime_type,
     std::vector<base::FilePath::StringType>* extensions);