docs(http): complete documentation (#4209)

http/cookie.ts

@@ -5,6 +5,11 @@
 
 import { assert } from "../assert/assert.ts";
 
+/**
+ * Represents an HTTP Cookie.
+ *
+ * @see {@link https://tools.ietf.org/html/rfc6265#section-4.1.1}
+ */
 export interface Cookie {
   /** Name of the cookie. */
   name: string;

http/etag.ts

@@ -1,35 +1,47 @@
 // Copyright 2018-2024 the Deno authors. All rights reserved. MIT license.
 
-/** Provides functions for dealing with and matching ETags, including
+/**
+ * Provides functions for dealing with and matching ETags, including
  * {@linkcode calculate} to calculate an etag for a given entity,
  * {@linkcode ifMatch} for validating if an ETag matches against a `If-Match`
  * header and {@linkcode ifNoneMatch} for validating an Etag against an
  * `If-None-Match` header.
  *
  * See further information on the `ETag` header on
- * [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag).
+ * {@link https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/ETag | MDN}.
  *
  * @module
  */
 
 import { encodeBase64 as base64Encode } from "../encoding/base64.ts";
 
-/** Just the part of `Deno.FileInfo` that is required to calculate an `ETag`,
- * so partial or user generated file information can be passed. */
+/**
+ * Just the part of {@linkcode Deno.FileInfo} that is required to calculate an `ETag`,
+ * so partial or user generated file information can be passed.
+ */
 export interface FileInfo {
+  /** The last modification time of the file. This corresponds to the `mtime`
+   * field from `stat` on Linux/Mac OS and `ftLastWriteTime` on Windows. This
+   * may not be available on all platforms. */
   mtime: Date | null;
+  /** The size of the file, in bytes. */
   size: number;
 }
 
-type Entity = string | Uint8Array | FileInfo;
+/** Represents an entity that can be used for generating an ETag. */
+export type Entity = string | Uint8Array | FileInfo;
 
 const encoder = new TextEncoder();
 
 const DEFAULT_ALGORITHM: AlgorithmIdentifier = "SHA-256";
 
+/** Options for {@linkcode calculate}. */
 export interface ETagOptions {
-  /** A digest algorithm to use to calculate the etag. Defaults to
-   * `"FNV32A"`. */
+  /**
+   * A digest algorithm to use to calculate the etag.
+   *
+   * @default {"FNV32A"}
+   */
   algorithm?: AlgorithmIdentifier;
 
   /** Override the default behavior of calculating the `ETag`, either forcing
@@ -77,7 +89,8 @@ async function calcFileInfo(
   }
 }
 
-/** Calculate an ETag for an entity. When the entity is a specific set of data
+/**
+ * Calculate an ETag for an entity. When the entity is a specific set of data
  * it will be fingerprinted as a "strong" tag, otherwise if it is just file
  * information, it will be calculated as a weak tag.
  *

http/negotiation.ts

@@ -12,6 +12,7 @@ import { preferredEncodings } from "./_negotiation/encoding.ts";
 import { preferredLanguages } from "./_negotiation/language.ts";
 import { preferredMediaTypes } from "./_negotiation/media_type.ts";
 
+/** Loose copy of {@linkcode Request}. */
 export type Request = {
   headers: {
     get(key: string): string | null;

http/server.ts

@@ -17,9 +17,9 @@ const INITIAL_ACCEPT_BACKOFF_DELAY = 5;
 const MAX_ACCEPT_BACKOFF_DELAY = 1000;
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandlerInfo} instead.
- *
  * Information about the connection a request arrived on.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandlerInfo} instead.
  */
 export interface ConnInfo {
   /** The local address of the connection. */
@@ -29,24 +29,24 @@ export interface ConnInfo {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandler} instead.
- *
  * A handler for HTTP requests. Consumes a request and connection information
  * and returns a response.
  *
  * If a handler throws, the server calling the handler will assume the impact
  * of the error is isolated to the individual request. It will catch the error
  * and close the underlying connection.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeHandler} instead.
  */
 export type Handler = (
   request: Request,
   connInfo: ConnInfo,
 ) => Response | Promise<Response>;
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead.
- *
  * Options for running an HTTP server.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead.
  */
 export interface ServerInit extends Partial<Deno.ListenOptions> {
   /** The handler to invoke for individual HTTP requests. */
@@ -61,9 +61,9 @@ export interface ServerInit extends Partial<Deno.ListenOptions> {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
- *
  * Used to construct an HTTP server.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
  */
 export class Server {
   #port?: number;
@@ -498,9 +498,9 @@ export class Server {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead.
- *
  * Additional serve options.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeInit} instead.
  */
 export interface ServeInit extends Partial<Deno.ListenOptions> {
   /** An AbortSignal to close the server and all connections. */
@@ -514,9 +514,9 @@ export interface ServeInit extends Partial<Deno.ListenOptions> {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeOptions} instead.
- *
  * Additional serve listener options.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeOptions} instead.
  */
 export interface ServeListenerOptions {
   /** An AbortSignal to close the server and all connections. */
@@ -530,8 +530,6 @@ export interface ServeListenerOptions {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
- *
  * Constructs a server, accepts incoming connections on the given listener, and
  * handles requests on these connections with the given handler.
  *
@@ -554,6 +552,8 @@ export interface ServeListenerOptions {
  * @param listener The listener to accept connections from.
  * @param handler The handler for individual HTTP requests.
  * @param options Optional serve options.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
  */
 export async function serveListener(
   listener: Deno.Listener,
@@ -577,8 +577,6 @@ function hostnameForDisplay(hostname: string) {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
- *
  * Serves HTTP requests with the given handler.
  *
  * You can specify an object with a port and hostname option, which is the
@@ -622,6 +620,8 @@ function hostnameForDisplay(hostname: string) {
  *
  * @param handler The handler for individual HTTP requests.
  * @param options The options. See `ServeInit` documentation for details.
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
  */
 export async function serve(
   handler: Handler,
@@ -664,6 +664,8 @@ export async function serve(
 }
 
 /**
+ * Initialization parameters for {@linkcode serveTls}.
+ *
  * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.ServeTlsOptions} instead.
  */
 export interface ServeTlsInit extends ServeInit {
@@ -681,8 +683,6 @@ export interface ServeTlsInit extends ServeInit {
 }
 
 /**
- * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
- *
  * Serves HTTPS requests with the given handler.
  *
  * You must specify `key` or `keyFile` and `cert` or `certFile` options.
@@ -740,6 +740,8 @@ export interface ServeTlsInit extends ServeInit {
  * @param handler The handler for individual HTTPS requests.
  * @param options The options. See `ServeTlsInit` documentation for details.
  * @returns
+ *
+ * @deprecated (will be removed after 1.0.0) Use {@linkcode Deno.serve} instead.
  */
 export async function serveTls(
   handler: Handler,

http/server_sent_event_stream.ts

@@ -5,6 +5,8 @@ const NEWLINE_REGEXP = /\r\n|\r|\n/;
 const encoder = new TextEncoder();
 
 /**
+ * Represents a message in the Server-Sent Event (SSE) protocol.
+ *
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#fields}
  */
 export interface ServerSentEventMessage {

http/status.ts

@@ -162,6 +162,7 @@ export const STATUS_CODE = {
   NetworkAuthenticationRequired: 511,
 } as const;
 
+/** An HTTP status code. */
 export type StatusCode = typeof STATUS_CODE[keyof typeof STATUS_CODE];
 
 /** A record of all the status codes text. */
@@ -231,6 +232,7 @@ export const STATUS_TEXT = {
   [STATUS_CODE.VariantAlsoNegotiates]: "Variant Also Negotiates",
 } as const;
 
+/** An HTTP status text. */
 export type StatusText = typeof STATUS_TEXT[keyof typeof STATUS_TEXT];
 
 /** An HTTP status that is a informational (1XX). */
@@ -311,6 +313,7 @@ export type ServerErrorStatus =
 /** An HTTP status that is an error (4XX and 5XX). */
 export type ErrorStatus = ClientErrorStatus | ServerErrorStatus;
 
+/** Returns whether the provided number is a valid HTTP status code. */
 export function isStatus(status: number): status is StatusCode {
   return Object.values(STATUS_CODE).includes(status as StatusCode);
 }