@nestia/sdk 14.0.0 → 14.0.2

package/src/generates/internal/SdkWebSocketParameterProgrammer.ts

@@ -1,4 +1,5 @@
 import {
+  type Expression,
   type ParameterDeclaration,
   type TypeNode,
   factory,
@@ -6,30 +7,208 @@ import {
 
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
+import { ITypedWebSocketRouteParameter } from "../../structures/ITypedWebSocketRouteParameter";
+import { StringUtil } from "../../utils/StringUtil";
 import { SdkAliasCollection } from "./SdkAliasCollection";
 
+/**
+ * The parameters of a WebSocket route's SDK function.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace decides the identifiers, lists the entries, and writes the declarations, as the HTTP one does.
+ * @evidence contracts/common.md#clear-and-simple-design Several small functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifiers are decided once.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkWebSocketParameterProgrammer {
+  /**
+   * One parameter of a WebSocket route: its key and its type.
+   *
+   * @evidence contracts/common.md#principled-implementation The record is what a declaration needs.
+   * @evidence contracts/common.md#clear-and-simple-design A two-member record.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.IEntry composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export interface IEntry {
     key: string;
     type: TypeNode;
   }
 
+  /**
+   * The identifiers one WebSocket route's SDK function and `path()` use,
+   * decided once so the two cannot disagree; the HTTP counterpart,
+   * `SdkHttpParameterProgrammer.INames`, gives the rules.
+   *
+   * Path parameters are the user's names. `query` and `provider` are the SDK's
+   * own: the positional parameters, or the `props` keys in keyword mode, that
+   * carry the query object and the provider, so they yield to a path parameter
+   * of the same name instead of repeating it. A `props` key shadows nothing, so
+   * it yields to nothing else.
+   *
+   * @evidence contracts/common.md#principled-implementation One decision serves the two scopes.
+   * @evidence contracts/common.md#clear-and-simple-design A record of names and two lookups.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It is a type and adds no runtime behavior.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export interface INames {
+    connection: string;
+    props: string;
+    query: string;
+    provider: string;
+    url: string;
+    connector: string;
+    driver: string;
+    variables: string;
+    location: string;
+    key: string;
+    value: string;
+    elem: string;
+
+    /**
+     * Local identifier of a path parameter in positional mode.
+     *
+     * @evidence contracts/common.md#principled-implementation A path parameter keeps its name unless the SDK cannot change the name it collides with.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames.parameter composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
+    parameter: (p: ITypedWebSocketRouteParameter.IParam) => string;
+
+    /**
+     * Reads a parameter, or one of `query` and `provider`, by its key.
+     *
+     * @evidence contracts/common.md#principled-implementation The read follows the mode of the function.
+     * @evidence contracts/common.md#clear-and-simple-design One lookup.
+     * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the decision.
+     * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+     * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.INames.access composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+     */
+    access: (key: string) => Expression;
+  }
+
+  /**
+   * Decides the identifiers of a WebSocket route's function and `path()` once.
+   *
+   * @evidence contracts/common.md#principled-implementation The fixed names each scope references are collected, and `query` and `provider` yield to a path parameter of the same name.
+   * @evidence contracts/common.md#clear-and-simple-design One function over the scope sets.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Only shadowed names are renamed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getNames composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
+  export const getNames = (props: {
+    project: INestiaProject;
+    route: ITypedWebSocketRoute;
+  }): INames => {
+    const { project, route } = props;
+    // names each scope references and the SDK cannot change
+    const functional: string[] = [route.name, "WebSocketConnector"];
+    const path: string[] = [
+      ...(route.pathParameters.length !== 0 ? ["PathParameter"] : []),
+      ...(route.query !== null
+        ? ["URLSearchParams", "Object", "Array", "String", "undefined"]
+        : []),
+    ];
+    const locals: Map<ITypedWebSocketRouteParameter.IParam, string> = new Map();
+    if (project.config.keyword !== true)
+      for (const p of route.pathParameters)
+        locals.set(
+          p,
+          StringUtil.escapeDuplicate([
+            ...functional,
+            ...path,
+            ...route.pathParameters.filter((q) => q !== p).map((q) => q.name),
+            ...locals.values(),
+          ])(p.name),
+        );
+    // `query` and `provider` sit beside the path parameters, as parameters or
+    // as `props` keys. Every other own identifier avoids the positional
+    // path parameters its scope reads where it is visible: all of them for
+    // the function's locals, `variables`, and `location`, none for the
+    // loop's `key` and `value`, whose header reads only the query, and for
+    // `elem`.
+    const keys: string[] = route.pathParameters.map(
+      (p) => locals.get(p) ?? p.name,
+    );
+    const positional: string[] = [...locals.values()];
+    const own =
+      (fixed: string[], reads: string[], taken: string[]) =>
+      (name: string): string => {
+        const escaped: string = StringUtil.escapeDuplicate([
+          ...fixed,
+          ...reads,
+          ...taken,
+        ])(name);
+        taken.push(escaped);
+        return escaped;
+      };
+    const shared: string[] = [];
+    const $props: string = own([...functional, ...path], [], shared)("props");
+    // Positional `query` and `provider` also yield to the names their scopes
+    // reference; as `props` keys they shadow nothing, so a route named
+    // `query` keeps its `query` key.
+    const beside = (fixed: string[]) =>
+      own(project.config.keyword === true ? [] : fixed, keys, shared);
+    const $query: string = beside([...functional, ...path])("query");
+    const $provider: string = beside(functional)("provider");
+    const inFunction: string[] = [...shared];
+    const inPath: string[] = [...shared];
+    const names: Omit<INames, "parameter" | "access"> = {
+      props: $props,
+      query: $query,
+      provider: $provider,
+      connection: own(functional, positional, inFunction)("connection"),
+      url: own(functional, positional, inFunction)("url"),
+      connector: own(functional, positional, inFunction)("connector"),
+      driver: own(functional, positional, inFunction)("driver"),
+      variables: own(path, positional, inPath)("variables"),
+      location: own(path, positional, inPath)("location"),
+      key: own(path, [], inPath)("key"),
+      value: own(path, [], inPath)("value"),
+      elem: own(path, [], inPath)("elem"),
+    };
+    return {
+      ...names,
+      parameter: (p) => locals.get(p) ?? p.name,
+      access: (key) =>
+        project.config.keyword === true
+          ? factory.createPropertyAccessExpression(
+              factory.createIdentifier(names.props),
+              key,
+            )
+          : factory.createIdentifier(key),
+    };
+  };
+
+  /**
+   * Returns the entries of a WebSocket route: its path parameters, its query,
+   * and its provider.
+   *
+   * @evidence contracts/common.md#principled-implementation The query exists only when the route has one, and the provider is included only when the caller requests it.
+   * @evidence contracts/common.md#clear-and-simple-design One list.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The order is the call order.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getEntries composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getEntries = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
     provider: boolean;
     prefix: boolean;
   }): IEntry[] => {
+    const names: INames = getNames(props);
     const prefix: string = props.prefix ? `${props.route.name}.` : "";
     return [
       ...props.route.pathParameters.map((p) => ({
-        key: p.name,
+        key: names.parameter(p),
         type: SdkAliasCollection.name(p),
       })),
       ...(props.route.query
         ? [
             {
-              key: "query",
+              key: names.query,
               type: factory.createTypeReferenceNode(`${prefix}Query`),
             },
           ]
@@ -37,7 +216,7 @@ export namespace SdkWebSocketParameterProgrammer {
       ...(props.provider
         ? [
             {
-              key: "provider",
+              key: names.provider,
               type: factory.createTypeReferenceNode(`${prefix}Provider`),
             },
           ]
@@ -45,6 +224,16 @@ export namespace SdkWebSocketParameterProgrammer {
     ];
   };
 
+  /**
+   * Returns the parameter declarations of a WebSocket route's function: `props`
+   * in keyword mode, and one positional parameter per entry otherwise.
+   *
+   * @evidence contracts/common.md#principled-implementation The names come from `getNames`.
+   * @evidence contracts/common.md#clear-and-simple-design One function of two modes.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The two modes share the entries.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.getParameterDeclarations composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getParameterDeclarations = (props: {
     project: INestiaProject;
     route: ITypedWebSocketRoute;
@@ -54,6 +243,7 @@ export namespace SdkWebSocketParameterProgrammer {
     const entries: IEntry[] = getEntries(props);
     if (entries.length === 0) return [];
     else if (props.project.config.keyword === true) {
+      const names: INames = getNames(props);
       const typeName: string = props.prefix
         ? `${props.route.name}.Props`
         : "Props";
@@ -62,14 +252,14 @@ export namespace SdkWebSocketParameterProgrammer {
         : factory.createTypeReferenceNode("Omit", [
             factory.createTypeReferenceNode(typeName),
             factory.createLiteralTypeNode(
-              factory.createStringLiteral("provider"),
+              factory.createStringLiteral(names.provider),
             ),
           ]);
       return [
         factory.createParameterDeclaration(
           undefined,
           undefined,
-          "props",
+          names.props,
           undefined,
           node,
         ),
@@ -86,6 +276,16 @@ export namespace SdkWebSocketParameterProgrammer {
     );
   };
 
+  /**
+   * Reports whether the route's path holds no parameter, so `path()` takes
+   * none.
+   *
+   * @evidence contracts/common.md#principled-implementation The route has no path parameter and no query.
+   * @evidence contracts/common.md#clear-and-simple-design One expression.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketParameterProgrammer.isPathEmpty composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const isPathEmpty = (route: ITypedWebSocketRoute): boolean =>
     route.pathParameters.length === 0 && route.query === null;
 }

package/src/generates/internal/SdkWebSocketRouteProgrammer.ts

@@ -6,57 +6,100 @@ import {
   type TypeNode,
   factory,
 } from "@ttsc/factory";
-import { IJsDocTagInfo } from "typia";
 
 import { IdentifierFactory } from "../../factories/IdentifierFactory";
 import { INestiaProject } from "../../structures/INestiaProject";
 import { ITypedWebSocketRoute } from "../../structures/ITypedWebSocketRoute";
-import { StringUtil } from "../../utils/StringUtil";
 import { FilePrinter } from "./FilePrinter";
 import { ImportDictionary } from "./ImportDictionary";
 import { SdkImportWizard } from "./SdkImportWizard";
 import { SdkWebSocketNamespaceProgrammer } from "./SdkWebSocketNamespaceProgrammer";
 import { SdkWebSocketParameterProgrammer } from "./SdkWebSocketParameterProgrammer";
 
+/**
+ * Writes a WebSocket route into the SDK: its function and its namespace.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace prints the async function that opens the connection with `tgrid`.
+ * @evidence contracts/common.md#clear-and-simple-design One public function and the writers.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The identifiers are decided by the parameter programmer.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketRouteProgrammer composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SdkWebSocketRouteProgrammer {
+  /**
+   * Returns the function and the namespace of a WebSocket route.
+   *
+   * @evidence contracts/common.md#principled-implementation The two nodes are composed together so they share names.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The shape follows the route.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SdkWebSocketRouteProgrammer.write composes SDK syntax, identifiers or import bindings; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const write =
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute): Statement[] => [
       FilePrinter.description(
         writeFunction(project)(importer)(route),
-        writeDescription(route),
+        writeDescription(project, route),
       ),
       SdkWebSocketNamespaceProgrammer.write(project)(importer)(route),
     ];
 
-  const writeDescription = (route: ITypedWebSocketRoute): string => {
+  const writeDescription = (
+    project: INestiaProject,
+    route: ITypedWebSocketRoute,
+  ): string => {
     // MAIN DESCRIPTION
     const comments: string[] = route.description
       ? route.description.split("\n")
       : [];
 
-    // COMMENT TAGS
-    const tags: IJsDocTagInfo[] = route.jsDocTags.filter(
-      (tag) =>
-        tag.name !== "param" ||
-        [...route.pathParameters, ...(route.query ? [route.query] : [])]
-          .filter((p) => p.category === "param" || p.category === "query")
-          .some((p) => p.name === tag.text?.[0]?.text),
-    );
-    if (tags.length !== 0) {
-      const content: string[] = tags.map((t) =>
-        t.text?.length
-          ? `@${t.name} ${t.text.map((e) => e.text).join("")}`
-          : `@${t.name}`,
-      );
-      comments.push("", ...new Set(content));
-    }
+    // COMMENT TAGS, each `@param` naming what the SDK function declares,
+    // which yields on a collision
+    const names: SdkWebSocketParameterProgrammer.INames =
+      SdkWebSocketParameterProgrammer.getNames({ project, route });
+    const declared = (name: string | undefined): string | null => {
+      const path = route.pathParameters.find((p) => p.name === name);
+      const key: string | null =
+        path !== undefined
+          ? project.config.keyword === true
+            ? path.name
+            : names.parameter(path)
+          : route.query !== null && route.query.name === name
+            ? names.query
+            : null;
+      return key === null
+        ? null
+        : project.config.keyword === true
+          ? `${names.props}.${key}`
+          : key;
+    };
+    const tags: string[] = route.jsDocTags
+      .map((tag): string | null => {
+        if (tag.name !== "param")
+          return FilePrinter.jsDocTag(
+            tag.name,
+            tag.text?.map((e) => e.text).join("") ?? "",
+          );
+        const name: string | null = declared(tag.text?.[0]?.text);
+        return name === null
+          ? null
+          : FilePrinter.jsDocTag(
+              `param ${name}`,
+              tag.text?.find((e) => e.kind === "text")?.text ?? "",
+            );
+      })
+      .filter((tag): tag is string => tag !== null);
+    // apart from the description, when there is one
+    if (tags.length !== 0)
+      comments.push(...(comments.length !== 0 ? [""] : []), ...new Set(tags));
 
     // POSTFIX
     if (!!comments.length) comments.push("");
     comments.push(
-      `@controller ${route.controller.class.name}.${route.name}`,
+      // the public name, kept by a route declared under a local one
+      `@controller ${route.controller.class.name}.${route.key}`,
       `@path ${route.path}`,
       `@nestia Generated by Nestia - https://github.com/samchon/nestia`,
     );
@@ -67,9 +110,8 @@ export namespace SdkWebSocketRouteProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute): Statement => {
-      const connection: string = StringUtil.escapeDuplicate([route.name])(
-        "connection",
-      );
+      const names: SdkWebSocketParameterProgrammer.INames =
+        SdkWebSocketParameterProgrammer.getNames({ project, route });
       return factory.createFunctionDeclaration(
         [
           factory.createModifier(SyntaxKind.ExportKeyword),
@@ -80,7 +122,7 @@ export namespace SdkWebSocketRouteProgrammer {
         undefined,
         [
           IdentifierFactory.parameter(
-            connection,
+            names.connection,
             factory.createTypeReferenceNode(
               SdkImportWizard.IConnection(importer),
               [factory.createTypeReferenceNode(`${route.name}.Header`)],
@@ -97,7 +139,7 @@ export namespace SdkWebSocketRouteProgrammer {
           factory.createTypeReferenceNode(`${route.name}.Output`),
         ]),
         factory.createBlock(
-          writeFunctionBody(project)(importer)(route)(connection),
+          writeFunctionBody(project)(importer)(route)(names),
           true,
         ),
       );
@@ -107,18 +149,11 @@ export namespace SdkWebSocketRouteProgrammer {
     (project: INestiaProject) =>
     (importer: ImportDictionary) =>
     (route: ITypedWebSocketRoute) =>
-    (connection: string): Statement[] => {
-      const access = (key: string) =>
-        project.config.keyword === true
-          ? factory.createPropertyAccessExpression(
-              factory.createIdentifier("props"),
-              key,
-            )
-          : factory.createIdentifier(key);
+    (names: SdkWebSocketParameterProgrammer.INames): Statement[] => {
       return [
-        local("url")(factory.createTypeReferenceNode("string"))(
+        local(names.url)(factory.createTypeReferenceNode("string"))(
           joinPath(
-            connection,
+            names.connection,
             factory.createCallExpression(
               factory.createPropertyAccessExpression(
                 factory.createIdentifier(route.name),
@@ -127,7 +162,7 @@ export namespace SdkWebSocketRouteProgrammer {
               [],
               project.config.keyword === true &&
                 SdkWebSocketParameterProgrammer.isPathEmpty(route) === false
-                ? [factory.createIdentifier("props")]
+                ? [factory.createIdentifier(names.props)]
                 : SdkWebSocketParameterProgrammer.getEntries({
                     project,
                     route,
@@ -137,7 +172,7 @@ export namespace SdkWebSocketRouteProgrammer {
             ),
           ),
         ),
-        local("connector")(
+        local(names.connector)(
           factory.createTypeReferenceNode(
             importer.external({
               declaration: false,
@@ -166,7 +201,7 @@ export namespace SdkWebSocketRouteProgrammer {
               factory.createAsExpression(
                 factory.createBinaryExpression(
                   factory.createPropertyAccessExpression(
-                    factory.createIdentifier(connection),
+                    factory.createIdentifier(names.connection),
                     "headers",
                   ),
                   factory.createToken(SyntaxKind.QuestionQuestionToken),
@@ -174,7 +209,7 @@ export namespace SdkWebSocketRouteProgrammer {
                 ),
                 factory.createKeywordTypeNode(SyntaxKind.AnyKeyword),
               ),
-              access("provider"),
+              names.access(names.provider),
             ],
           ),
         ),
@@ -182,15 +217,15 @@ export namespace SdkWebSocketRouteProgrammer {
           factory.createAwaitExpression(
             factory.createCallExpression(
               factory.createPropertyAccessExpression(
-                factory.createIdentifier("connector"),
+                factory.createIdentifier(names.connector),
                 "connect",
               ),
               undefined,
-              [factory.createIdentifier("url")],
+              [factory.createIdentifier(names.url)],
             ),
           ),
         ),
-        local("driver")(
+        local(names.driver)(
           factory.createTypeReferenceNode(
             importer.external({
               declaration: true,
@@ -203,7 +238,7 @@ export namespace SdkWebSocketRouteProgrammer {
         )(
           factory.createCallExpression(
             factory.createPropertyAccessExpression(
-              factory.createIdentifier("connector"),
+              factory.createIdentifier(names.connector),
               "getDriver",
             ),
             undefined,
@@ -213,8 +248,8 @@ export namespace SdkWebSocketRouteProgrammer {
         factory.createReturnStatement(
           factory.createObjectLiteralExpression(
             [
-              factory.createShorthandPropertyAssignment("connector"),
-              factory.createShorthandPropertyAssignment("driver"),
+              writeOutputMember("connector", names.connector),
+              writeOutputMember("driver", names.driver),
               factory.createPropertyAssignment(
                 factory.createIdentifier("reconnect"),
                 factory.createArrowFunction(
@@ -226,11 +261,11 @@ export namespace SdkWebSocketRouteProgrammer {
                   factory.createAwaitExpression(
                     factory.createCallExpression(
                       factory.createPropertyAccessExpression(
-                        factory.createIdentifier("connector"),
+                        factory.createIdentifier(names.connector),
                         factory.createIdentifier("connect"),
                       ),
                       undefined,
-                      [factory.createIdentifier("url")],
+                      [factory.createIdentifier(names.url)],
                     ),
                   ),
                 ),
@@ -243,6 +278,12 @@ export namespace SdkWebSocketRouteProgrammer {
     };
 }
 
+/** A member of the returned `Output`, shorthand when its local has its name. */
+const writeOutputMember = (key: string, local: string) =>
+  key === local
+    ? factory.createShorthandPropertyAssignment(key)
+    : factory.createPropertyAssignment(key, factory.createIdentifier(local));
+
 const local = (name: string) => (type: TypeNode) => (expression: Expression) =>
   factory.createVariableStatement(
     [],

package/src/generates/internal/SwaggerDescriptionComposer.ts

@@ -1,6 +1,28 @@
 import { IJsDocTagInfo } from "typia";
 
+/**
+ * Composes the title or summary and the description of a document member from
+ * its comment.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace reads the explicit tag, and otherwise takes the first line of the description when it is a sentence.
+ * @evidence contracts/common.md#clear-and-simple-design Three functions.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The tag has priority over the derived text.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+ * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+ */
 export namespace SwaggerDescriptionComposer {
+  /**
+   * Returns the `summary` or `title` and the `description` of a member.
+   *
+   * The explicit tag is the summary; otherwise the description's first line,
+   * without its final period, when that line ends with one.
+   *
+   * @evidence contracts/common.md#principled-implementation The derived summary is only ever a whole sentence, and a description that is not a sentence has none.
+   * @evidence contracts/common.md#clear-and-simple-design One function.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The kind is the caller's choice.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.compose composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const compose = <Kind extends "summary" | "title">(props: {
     description: string | null;
     jsDocTags: IJsDocTagInfo[];
@@ -28,6 +50,17 @@ export namespace SwaggerDescriptionComposer {
     } as any;
   };
 
+  /**
+   * Returns the first text part of the first JSDoc tag with the name and a text
+   * array, matching the parameter name when one is given. Returns undefined
+   * when that selected tag has no text part.
+   *
+   * @evidence contracts/common.md#principled-implementation A matching tag with a text array is selected, then its first text part is returned if present.
+   * @evidence contracts/common.md#clear-and-simple-design One search.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It reads the tags.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.descriptionFromJsDocTag composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const descriptionFromJsDocTag = (props: {
     jsDocTags: IJsDocTagInfo[];
     tag: string;
@@ -48,6 +81,15 @@ export namespace SwaggerDescriptionComposer {
       : undefined;
   };
 
+  /**
+   * Returns the text of every JSDoc tag with the name and a non-empty text.
+   *
+   * @evidence contracts/common.md#principled-implementation The tags are filtered, then read.
+   * @evidence contracts/common.md#clear-and-simple-design One filter and one map.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts An empty text is not returned.
+   * @evidence contracts/common.md#meaningful-documentation The comment states what the declaration produces and its result.
+   * @evidenceExclude contracts/portability.md#os-neutral-implementation SwaggerDescriptionComposer.getJsDocTexts composes OpenAPI data; it does not resolve native file identity or launch a process. Source resolution and file emission belong to their filesystem owners.
+   */
   export const getJsDocTexts = (props: {
     jsDocTags: IJsDocTagInfo[];
     name: string;
@@ -60,5 +102,9 @@ export namespace SwaggerDescriptionComposer {
           tag.text.find((elem) => elem.kind === "text" && elem.text.length) !==
             undefined,
       )
-      .map((tag) => tag.text!.find((elem) => elem.kind === "text")!.text);
+      .map(
+        (tag) =>
+          tag.text!.find((elem) => elem.kind === "text" && elem.text.length)!
+            .text,
+      );
 }