docs(media_types): complete documentation (#4219)

denoland · Jan 18, 2024 · 10c5121 · 10c5121
1 parent 53d27bb
commit 10c5121
Show file tree

Hide file tree

Showing 6 changed files with 29 additions and 37 deletions.
diff --git a/media_types/content_type.ts b/media_types/content_type.ts
@@ -7,14 +7,20 @@ import { formatMediaType } from "./format_media_type.ts";
 import type { db } from "./_db.ts";
 import { typeByExtension } from "./type_by_extension.ts";
 
-type DB = typeof db;
-type ContentTypeToExtension = {
+/** MIME-types database. */
+export type DB = typeof db;
+/** Maps content types to their corresponding file extensions. */
+export type ContentTypeToExtension = {
+  /**
+   * Maps each content type key to its corresponding file extension.
+   */
   [K in keyof DB]: DB[K] extends { "extensions": readonly string[] }
     ? DB[K]["extensions"][number]
     : never;
 };
 
-type KnownExtensionOrType =
+/** Known extension or type. Used in {@linkcode contentType}. */
+export type KnownExtensionOrType =
   | keyof ContentTypeToExtension
   | ContentTypeToExtension[keyof ContentTypeToExtension]
   | `.${ContentTypeToExtension[keyof ContentTypeToExtension]}`;
@@ -39,10 +45,10 @@ type KnownExtensionOrType =
  * ```ts
  * import { contentType } from "https://deno.land/std@$STD_VERSION/media_types/content_type.ts";
  *
- * contentType(".json"); // `application/json; charset=UTF-8`
- * contentType("text/html"); // `text/html; charset=UTF-8`
- * contentType("text/html; charset=UTF-8"); // `text/html; charset=UTF-8`
- * contentType("txt"); // `text/plain; charset=UTF-8`
+ * contentType(".json"); // "application/json; charset=UTF-8"
+ * contentType("text/html"); // "text/html; charset=UTF-8"
+ * contentType("text/html; charset=UTF-8"); // "text/html; charset=UTF-8"
+ * contentType("txt"); // "text/plain; charset=UTF-8"
  * contentType("foo"); // undefined
  * contentType("file.json"); // undefined
  * ```

diff --git a/media_types/extension.ts b/media_types/extension.ts
@@ -13,9 +13,9 @@ import { extensionsByType } from "./extensions_by_type.ts";
  * ```ts
  * import { extension } from "https://deno.land/std@$STD_VERSION/media_types/extension.ts";
  *
- * extension("text/plain"); // `txt`
- * extension("application/json"); // `json`
- * extension("text/html; charset=UTF-8"); // `html`
+ * extension("text/plain"); // "txt"
+ * extension("application/json"); // "json"
+ * extension("text/html; charset=UTF-8"); // "html"
  * extension("application/foo"); // undefined
  * ```
  */

diff --git a/media_types/format_media_type.ts b/media_types/format_media_type.ts
@@ -15,7 +15,7 @@ import { isIterator, isToken, needsEncoding } from "./_util.ts";
  * ```ts
  * import { formatMediaType } from "https://deno.land/std@$STD_VERSION/media_types/format_media_type.ts";
  *
- * formatMediaType("text/plain", { charset: "UTF-8" }); // `text/plain; charset=UTF-8`
+ * formatMediaType("text/plain", { charset: "UTF-8" }); // "text/plain; charset=UTF-8"
  * ```
  */
 export function formatMediaType(

diff --git a/media_types/get_charset.ts b/media_types/get_charset.ts
@@ -13,10 +13,10 @@ import { db, type KeyOfDb } from "./_db.ts";
  * ```ts
  * import { getCharset } from "https://deno.land/std@$STD_VERSION/media_types/get_charset.ts";
  *
- * getCharset("text/plain"); // `UTF-8`
+ * getCharset("text/plain"); // "UTF-8"
  * getCharset("application/foo"); // undefined
- * getCharset("application/news-checkgroups"); // `US-ASCII`
- * getCharset("application/news-checkgroups; charset=UTF-8"); // `UTF-8`
+ * getCharset("application/news-checkgroups"); // "US-ASCII"
+ * getCharset("application/news-checkgroups; charset=UTF-8"); // "UTF-8"
  * ```
  */
 export function getCharset(type: string): string | undefined {

diff --git a/media_types/parse_media_type.ts b/media_types/parse_media_type.ts
@@ -5,11 +5,11 @@ import { consumeMediaParam, decode2331Encoding } from "./_util.ts";
 
 /**
  * Parses the media type and any optional parameters, per
- * [RFC 1521](https://datatracker.ietf.org/doc/html/rfc1521). Media types are
- * the values in `Content-Type` and `Content-Disposition` headers. On success
- * the function returns a tuple where the first element is the media type and
- * the second element is the optional parameters or `undefined` if there are
- * none.
+ * {@link https://datatracker.ietf.org/doc/html/rfc1521 | RFC 1521}. Media
+ * types are the values in `Content-Type` and `Content-Disposition` headers. On
+ * success the function returns a tuple where the first element is the media
+ * type and the second element is the optional parameters or `undefined` if
+ * there are none.
  *
  * The function will throw if the parsed value is invalid.
  *
@@ -20,23 +20,9 @@ import { consumeMediaParam, decode2331Encoding } from "./_util.ts";
  * @example
  * ```ts
  * import { parseMediaType } from "https://deno.land/std@$STD_VERSION/media_types/parse_media_type.ts";
- * import { assertEquals } from "https://deno.land/std@$STD_VERSION/assert/assert_equals.ts";
  *
- * assertEquals(
- *   parseMediaType("application/JSON"),
- *   [
- *     "application/json",
- *     undefined
- *   ]
- * );
- *
- * assertEquals(
- *   parseMediaType("text/html; charset=UTF-8"),
- *   [
- *     "text/html",
- *     { charset: "UTF-8" },
- *   ]
- * );
+ * parseMediaType("application/JSON"); // ["application/json", undefined]
+ * parseMediaType("text/html; charset=UTF-8"); // ["text/html", { charset: "UTF-8" }]
  * ```
  */
 export function parseMediaType(

diff --git a/media_types/type_by_extension.ts b/media_types/type_by_extension.ts
@@ -13,8 +13,8 @@ import { types } from "./_db.ts";
  * ```ts
  * import { typeByExtension } from "https://deno.land/std@$STD_VERSION/media_types/type_by_extension.ts";
  *
- * typeByExtension("js"); // `application/json`
- * typeByExtension(".HTML"); // `text/html`
+ * typeByExtension("js"); // "application/json"
+ * typeByExtension(".HTML"); // "text/html"
  * typeByExtension("foo"); // undefined
  * typeByExtension("file.json"); // undefined
  * ```