docs(http-server-js): Add JSDoc for server emitter APIs [skip chg] (#12250)

JavaScript server emitter consumers lack API guidance on how `$onEmit`,
`$lib`, and emitter options fit together. Document their roles, option
defaults, generated-output ownership, dry-run behavior, and
service/error limitations without changing emission behavior.

Preserves the existing deprecated testing-library guidance and leaves
generated helpers untouched.

Tracked in #12228.

Author: timotheeguerin

packages/http-server-js/src/index.ts

@@ -17,6 +17,18 @@ import { emitHttp } from "./http/index.js";
 
 export { $lib } from "./lib.js";
 
+/**
+ * TypeSpec emitter entry point that generates TypeScript server bindings for a single service.
+ *
+ * Replaces `src/generated` beneath the emitter output directory with server, model, and
+ * serialization modules. In a compiler dry run, builds the module tree without deleting or
+ * writing files. A program without a service produces a warning and no output; HTTP service
+ * errors disable HTTP bindings but do not stop model emission.
+ *
+ * @param context - Compiler-provided program, emitter options, and output directory.
+ * @throws If the program defines multiple services or encounters an unsupported emission
+ * feature. File-writing and formatting failures also reject the returned promise.
+ */
 export async function $onEmit(context: EmitContext<JsEmitterOptions>) {
   const jsCtx = await createInitialContext(context.program, context.options);
 

packages/http-server-js/src/lib.ts

@@ -4,25 +4,41 @@
 import type { JSONSchemaType } from "@typespec/compiler";
 import { createTypeSpecLibrary, paramMessage } from "@typespec/compiler";
 
+/**
+ * Configures the server bindings generated by the `$onEmit` entry point.
+ *
+ * Supply these options under `@typespec/http-server-js` in `tspconfig.yaml`.
+ * The emitter option schema registered by {@link $lib} defaults all boolean options
+ * to `false` and `datetime` to `"temporal-polyfill"`.
+ */
 export interface JsEmitterOptions {
-  /** If set to `true`, the emitter will generate a router that exposes an Express.js middleware function in addition to the ordinary Node.js HTTP server router.
-
-If this option is not set to `true`, the `expressMiddleware` property will not be present on the generated router. */
+  /**
+   * Generates an Express.js middleware adapter in addition to the Node.js HTTP server router.
+   * When disabled, the generated router has no `expressMiddleware` property.
+   * @default false
+   */
   express?: boolean;
 
-  /** By default, the emitter will create interfaces that represent all models in the service namespace. If this option is set
-to `true`, the emitter will only emit those types that are reachable from an HTTP operation. */
+  /**
+   * Limits generated types to those reachable from HTTP operations. By default, types in
+   * the service namespace and its nested namespaces are also included.
+   * @default false
+   */
   "omit-unreachable-types": boolean;
-  /** If set to `true`, the emitter will not format the generated code using Prettier. */
+  /**
+   * Skips Prettier formatting of generated source files.
+   * @default false
+   */
   "no-format": boolean;
 
   /**
-   * The type of datetime models to use for TypeSpecs DateTime and Duration types.
+   * Selects the JavaScript representation of TypeSpec date, time, and duration scalars.
    *
    * Options:
    * - `temporal-polyfill`: (Default) Uses the Temporal API from the `temporal-polyfill` package.
    * - `temporal`: Uses the native Temporal API, requires that your target environment supports it. This will become the default setting in the future.
    * - `date-duration`: Uses the built-in `Date` and a custom `Duration` type. Not recommended.
+   * @default "temporal-polyfill"
    */
   datetime?: "temporal-polyfill" | "temporal" | "date-duration";
 }
@@ -61,6 +77,11 @@ const EmitterOptionsSchema: JSONSchemaType<JsEmitterOptions> = {
   required: [],
 };
 
+/**
+ * TypeSpec library definition registering the server emitter's option schema, defaults,
+ * diagnostics, and dry-run support. Re-exported from the package entry point for the
+ * compiler to discover; `$onEmit` performs code generation.
+ */
 export const $lib = createTypeSpecLibrary({
   name: "@typespec/http-server-js",
   capabilities: {