feat(http): support inline documentation comments for response descriptions

.chronus/changes/feat-response-doc-2025-11-22-13-13-51.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/compiler"
+---
+
+Parse inline doc comments.
+Change formatter behavior to improve the readability of inline doc comments.

.chronus/changes/feat-response-doc-2025-11-25-23-40-21.md

@@ -0,0 +1,7 @@
+---
+changeKind: feature
+packages:
+  - "@typespec/http"
+---
+
+Associate parsed inline doc comments with response descriptions.

packages/compiler/src/core/parser.ts

@@ -417,6 +417,19 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa
     return { pos, docs, directives, decorators };
   }
 
+  function parseInlineDocComments(): {
+    pos: number;
+    docs: DocNode[];
+  } {
+    const docs: DocNode[] = [];
+    const [pos, addedDocs] = parseDocList();
+    for (const doc of addedDocs) {
+      docs.push(doc);
+    }
+
+    return { pos, docs };
+  }
+
   function parseTypeSpecScriptItemList(): Statement[] {
     const stmts: Statement[] = [];
     let seenBlocklessNs = false;
@@ -841,7 +854,9 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa
     if (token === Token.OpenParen) {
       const parameters = parseOperationParameters();
       parseExpected(Token.Colon);
-      const returnType = parseExpression();
+      // try to parse inline docs
+      const { docs } = parseInlineDocComments();
+      const returnType = parseExpression(docs);
 
       signature = {
         kind: SyntaxKind.OperationSignatureDeclaration,
@@ -1228,7 +1243,9 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa
     const { items: templateParameters, range: templateParametersRange } =
       parseTemplateParameterList();
     parseExpected(Token.Equals);
-    const value = parseExpression();
+    // try to parse inline docs
+    const { docs } = parseInlineDocComments();
+    const value = parseExpression(docs);
     parseExpected(Token.Semicolon);
     return {
       kind: SyntaxKind.AliasStatement,
@@ -1263,23 +1280,39 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa
     return undefined;
   }
 
-  function parseExpression(): Expression {
-    return parseUnionExpressionOrHigher();
+  function parseExpression(docs: DocNode[] = []): Expression {
+    return parseUnionExpressionOrHigher(docs);
   }
 
-  function parseUnionExpressionOrHigher(): Expression {
-    const pos = tokenPos();
+  function parseUnionExpressionOrHigher(exprDocs: DocNode[]): Expression {
     parseOptional(Token.Bar);
+    // try to parse inline docs
+    const { docs: rideSideDocs, pos } = parseInlineDocComments();
+    // doc comments right side of `|` take precedence over left side
+    // e.g.
+    // op foo: /** exprDocs */ | /** rideSideDocs */ MyModel;
+    const docs = rideSideDocs.length > 0 ? rideSideDocs : exprDocs;
     const node: Expression = parseIntersectionExpressionOrHigher();
+    const expr = {
+      ...node,
+      docs,
+      pos,
+    };
 
     if (token() !== Token.Bar) {
-      return node;
+      return expr;
     }
 
-    const options = [node];
+    const options = [expr];
     while (parseOptional(Token.Bar)) {
+      // try to parse inline docs
+      const { docs, pos } = parseInlineDocComments();
       const expr = parseIntersectionExpressionOrHigher();
-      options.push(expr);
+      options.push({
+        ...expr,
+        docs,
+        pos,
+      });
     }
 
     return {

packages/compiler/src/formatter/print/printer.ts

@@ -22,6 +22,7 @@ import {
   EnumMemberNode,
   EnumSpreadMemberNode,
   EnumStatementNode,
+  Expression,
   FunctionDeclarationStatementNode,
   FunctionParameterNode,
   IdentifierNode,
@@ -1267,12 +1268,29 @@ export function printNamespaceStatement(
   return [decorators, `namespace `, join(".", names), suffix];
 }
 
+function shouldWrapOperationSignatureDeclarationInNewLines(returnType: Expression) {
+  if (
+    returnType.kind === SyntaxKind.TypeReference ||
+    returnType.kind === SyntaxKind.ModelExpression
+  ) {
+    return returnType.docs && returnType.docs.length > 0;
+  }
+  return false;
+}
+
 export function printOperationSignatureDeclaration(
   path: AstPath<OperationSignatureDeclarationNode>,
   options: TypeSpecPrettierOptions,
   print: PrettierChildPrint,
 ) {
-  return ["(", path.call(print, "parameters"), "): ", path.call(print, "returnType")];
+  const node = path.node;
+  let closeParenColon = "): ";
+  // if inline doc comments on return type, move to new line
+  const shouldAddNewLine = shouldWrapOperationSignatureDeclarationInNewLines(node.returnType);
+  if (shouldAddNewLine) {
+    closeParenColon = "):\n";
+  }
+  return ["(", path.call(print, "parameters"), closeParenColon, path.call(print, "returnType")];
 }
 
 export function printOperationSignatureReference(

packages/compiler/test/formatter/formatter.test.ts

@@ -766,6 +766,85 @@ op foo(
         });
       });
     });
+
+    describe("inline doc comments", () => {
+      it("single inline expression", async () => {
+        await assertFormat({
+          code: `
+op foo(): /** inline doc comment */ { @statusCode _: 200; content: string; };`,
+          expected: `
+op foo():
+/** inline doc comment */
+{
+  @statusCode _: 200;
+  content: string;
+};`,
+        });
+      });
+
+      it("single model statement", async () => {
+        await assertFormat({
+          code: `
+model SuccessResponse {
+  @statusCode _: 200;
+  content: string;
+}
+op foo(): /** inline doc comment */
+SuccessResponse;`,
+          expected: `
+model SuccessResponse {
+  @statusCode _: 200;
+  content: string;
+}
+op foo():
+/** inline doc comment */
+SuccessResponse;`,
+        });
+      });
+
+      it("union expression", async () => {
+        await assertFormat({
+          code: `
+model Success201 { @statusCode _: 201; content: string; }
+model Success204 { @statusCode _: 204; content: string; }
+model Error400 { @statusCode _: 400; content: string; }
+
+op foo():
+/** 200 */
+{ @statusCode _: 200; content: string; } |
+/**
+ * 201
+ */
+Success201 | Success204 | Error400;`,
+          expected: `
+model Success201 {
+  @statusCode _: 201;
+  content: string;
+}
+model Success204 {
+  @statusCode _: 204;
+  content: string;
+}
+model Error400 {
+  @statusCode _: 400;
+  content: string;
+}
+
+op foo():
+  | /** 200 */
+    {
+      @statusCode _: 200;
+      content: string;
+    }
+  | /**
+     * 201
+     */
+    Success201
+  | Success204
+  | Error400;`,
+        });
+      });
+    });
   });
 
   describe("scalar", () => {

packages/compiler/test/parser.test.ts

@@ -1091,6 +1091,82 @@ describe("compiler: parser", () => {
         strictEqual(comments[0].parsedAsDocs, true);
       });
 
+      it("mark used block comment with parsedAsDocs at operation", () => {
+        const script = parse(
+          `
+        op foo(): /** One-liner */ |
+        { bar: string };
+      `,
+          { docs: true, comments: true },
+        );
+        const comments = script.comments;
+        strictEqual(comments[0].kind, SyntaxKind.BlockComment);
+        strictEqual(comments[0].parsedAsDocs, true);
+      });
+
+      describe("mark used block comment with parsedAsDocs at union", () => {
+        parseEach(
+          [
+            [
+              `
+                op foo(): | /** First-union */  
+                { bar: string } | /** Second-union */ { baz: string };
+              `,
+              (script) => {
+                const comments = script.comments;
+                strictEqual(comments[0].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[0].parsedAsDocs, true);
+                strictEqual(comments[1].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[1].parsedAsDocs, true);
+              },
+            ],
+            [
+              `
+              alias MyResponse = /** First-union */ { bar: string } | /** Second-union */ { baz: string };
+              op foo(): MyResponse;
+              `,
+              (script) => {
+                const comments = script.comments;
+                strictEqual(comments[0].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[0].parsedAsDocs, true);
+                strictEqual(comments[1].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[1].parsedAsDocs, true);
+              },
+            ],
+            [
+              `
+              model Second { baz: string };
+              union MyResponse { /** First-union */ { bar: string }; /** Second-union */ Second; };
+              op foo(): MyResponse;
+              `,
+              (script) => {
+                const comments = script.comments;
+                strictEqual(comments[0].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[0].parsedAsDocs, true);
+                strictEqual(comments[1].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[1].parsedAsDocs, true);
+              },
+            ],
+            [
+              `
+              /** This is Second model */
+              model Second { baz: string };
+              union MyResponse { /** First-union */ { bar: string }; /** Second-union */ Second; };
+              op foo(): /** Override MyResponse union */ MyResponse | /** Override third-union */ { qux: string };
+              `,
+              (script) => {
+                const comments = script.comments;
+                strictEqual(comments[0].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[0].parsedAsDocs, true);
+                strictEqual(comments[1].kind, SyntaxKind.BlockComment);
+                strictEqual(comments[1].parsedAsDocs, true);
+              },
+            ],
+          ],
+          { docs: true, comments: true },
+        );
+      });
+
       it("other comments are not marked with parsedAsDocs", () => {
         const script = parse(
           `