Doc comment used to set @doc value (microsoft#1921)

Author: timotheeguerin

common/changes/@typespec/compiler/feature-doc-comment-real-doc_2023-05-10-16-25.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "**Feature** Doc comment will be applied as the doc for types unless an explicit @doc is provided.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/http/feature-doc-comment-real-doc_2023-05-10-16-25.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/http",
+      "comment": "Uptake doc comment changes",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/http"
+}

common/changes/@typespec/openapi3/feature-doc-comment-real-doc_2023-05-10-16-25.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/openapi3",
+      "comment": "Uptake doc comment changes. Standard built-in scalar will not have the description included as they are inlined.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/openapi3"
+}

common/changes/@typespec/protobuf/feature-doc-comment-real-doc_2023-05-10-16-25.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/protobuf",
+      "comment": "Uptake doc comment changes",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@typespec/protobuf"
+}

packages/compiler/core/checker.ts

@@ -1,4 +1,4 @@
-import { getDeprecated, getIndexer } from "../lib/decorators.js";
+import { $docFromComment, getDeprecated, getIndexer } from "../lib/decorators.js";
 import { createSymbol, createSymbolTable } from "./binder.js";
 import { ProjectionError, compilerAssert } from "./diagnostics.js";
 import { validateInheritanceDiscriminatedUnions } from "./helpers/discriminator-utils.js";
@@ -29,6 +29,7 @@ import {
   DecoratorExpressionNode,
   Diagnostic,
   DiagnosticTarget,
+  DocContent,
   Enum,
   EnumMember,
   EnumMemberNode,
@@ -2959,7 +2960,20 @@ export function createChecker(program: Program): Checker {
     type.decorators = checkDecorators(type, prop, mapper);
     const parentTemplate = getParentTemplateNode(prop);
     linkMapper(type, mapper);
+
     if (!parentTemplate || shouldCreateTypeForTemplate(parentTemplate, mapper)) {
+      if (
+        prop.parent?.parent?.kind === SyntaxKind.OperationSignatureDeclaration &&
+        prop.parent.parent.parent?.kind === SyntaxKind.OperationStatement
+      ) {
+        const doc = extractParamDoc(prop.parent.parent.parent, type.name);
+        if (doc) {
+          type.decorators.unshift({
+            decorator: $docFromComment,
+            args: [{ value: createLiteralType(doc) }],
+          });
+        }
+      }
       finishType(type);
     }
 
@@ -5270,12 +5284,56 @@ function linkMapper<T extends Type>(typeDef: T, mapper?: TypeMapper) {
   }
 }
 
+function extractMainDoc(type: Type): string | undefined {
+  if (type.node?.docs === undefined) {
+    return undefined;
+  }
+  let mainDoc: string = "";
+  for (const doc of type.node.docs) {
+    mainDoc += getDocContent(doc.content);
+  }
+  return mainDoc;
+}
+
+function extractParamDoc(node: OperationStatementNode, paramName: string): string | undefined {
+  if (node.docs === undefined) {
+    return undefined;
+  }
+  for (const doc of node.docs) {
+    for (const tag of doc.tags) {
+      if (tag.kind === SyntaxKind.DocParamTag && tag.paramName.sv === paramName) {
+        return getDocContent(tag.content);
+      }
+    }
+  }
+  return undefined;
+}
+
+function getDocContent(content: readonly DocContent[]) {
+  const docs = [];
+  for (const node of content) {
+    compilerAssert(
+      node.kind === SyntaxKind.DocText,
+      "No other doc content node kinds exist yet. Update this code appropriately when more are added."
+    );
+    docs.push(node.text);
+  }
+  return docs.join("");
+}
+
 function finishTypeForProgramAndChecker<T extends Type>(
   program: Program,
   typePrototype: TypePrototype,
   typeDef: T
 ): T {
   if ("decorators" in typeDef) {
+    const docComment = extractMainDoc(typeDef);
+    if (docComment) {
+      typeDef.decorators.unshift({
+        decorator: $docFromComment,
+        args: [{ value: program.checker.createLiteralType(docComment) }],
+      });
+    }
     for (const decApp of typeDef.decorators) {
       applyDecoratorToType(program, decApp, typeDef);
     }

packages/compiler/core/parser.ts

@@ -2210,7 +2210,7 @@ function createParser(code: string | SourceFile, options: ParseOptions = {}): Pa
   }
 
   function parseDocList(): [pos: number, nodes: DocNode[]] {
-    if (docRanges.length === 0 || !options.docs) {
+    if (docRanges.length === 0 || options.docs === false) {
       return [tokenPos(), []];
     }
     const docs: DocNode[] = [];

packages/compiler/formatter/parser.ts

@@ -8,7 +8,7 @@ export function parse(
   parsers: { [parserName: string]: Parser },
   opts: ParserOptions & { parentParser?: string }
 ): TypeSpecScriptNode {
-  const result = typespecParse(text, { comments: true });
+  const result = typespecParse(text, { comments: true, docs: false });
   const errors = result.parseDiagnostics.filter((x) => x.severity === "error");
   if (errors.length > 0 && !result.printable) {
     throw new PrettierParserError(errors[0]);

packages/compiler/lib/decorators.ts

@@ -44,21 +44,6 @@ function replaceTemplatedStringFromProperties(formatString: string, sourceObject
   });
 }
 
-function setTemplatedStringProperty(
-  key: symbol,
-  program: Program,
-  target: Type,
-  text: string,
-  sourceObject?: Type
-) {
-  // If an object was passed in, use it to format the documentation string
-  if (sourceObject) {
-    text = replaceTemplatedStringFromProperties(text, sourceObject);
-  }
-
-  program.stateMap(key).set(target, text);
-}
-
 function createStateSymbol(name: string) {
   return Symbol.for(`TypeSpec.${name}`);
 }
@@ -79,14 +64,31 @@ export function $summary(
   text: string,
   sourceObject: Type
 ) {
-  setTemplatedStringProperty(summaryKey, context.program, target, text, sourceObject);
+  if (sourceObject) {
+    text = replaceTemplatedStringFromProperties(text, sourceObject);
+  }
+
+  context.program.stateMap(summaryKey).set(target, text);
 }
 
 export function getSummary(program: Program, type: Type): string | undefined {
   return program.stateMap(summaryKey).get(type);
 }
 
 const docsKey = createStateSymbol("docs");
+export interface DocData {
+  /**
+   * Doc value.
+   */
+  value: string;
+
+  /**
+   * How was the doc set.
+   * - `@doc` means the `@doc` decorator was used
+   * - `comment` means it was set from a `/** comment * /`
+   */
+  source: "@doc" | "comment";
+}
 /**
  * @doc attaches a documentation string. Works great with multi-line string literals.
  *
@@ -97,13 +99,42 @@ const docsKey = createStateSymbol("docs");
  */
 export function $doc(context: DecoratorContext, target: Type, text: string, sourceObject?: Type) {
   validateDecoratorUniqueOnNode(context, target, $doc);
-  setTemplatedStringProperty(docsKey, context.program, target, text, sourceObject);
+  if (sourceObject) {
+    text = replaceTemplatedStringFromProperties(text, sourceObject);
+  }
+  setDocData(context.program, target, { value: text, source: "@doc" });
 }
 
-export function getDoc(program: Program, target: Type): string | undefined {
+/**
+ * @internal to be used to set the `@doc` from doc comment.
+ */
+export function $docFromComment(context: DecoratorContext, target: Type, text: string) {
+  setDocData(context.program, target, { value: text, source: "comment" });
+}
+
+function setDocData(program: Program, target: Type, data: DocData) {
+  program.stateMap(docsKey).set(target, data);
+}
+/**
+ * Get the documentation information for the given type. In most cases you probably just want to use {@link getDoc}
+ * @param program Program
+ * @param target Type
+ * @returns Doc data with source information.
+ */
+export function getDocData(program: Program, target: Type): DocData | undefined {
   return program.stateMap(docsKey).get(target);
 }
 
+/**
+ * Get the documentation string for the given type.
+ * @param program Program
+ * @param target Type
+ * @returns Documentation value
+ */
+export function getDoc(program: Program, target: Type): string | undefined {
+  return getDocData(program, target)?.value;
+}
+
 export function $inspectType(program: Program, target: Type, text: string) {
   // eslint-disable-next-line no-console
   if (text) console.log(text);

packages/compiler/server/type-details.ts

@@ -1,5 +1,11 @@
-import { compilerAssert, DocContent, Program, SyntaxKind, Type } from "../core/index.js";
-import { getDoc } from "../lib/decorators.js";
+import {
+  compilerAssert,
+  DocContent,
+  getDocData,
+  Program,
+  SyntaxKind,
+  Type,
+} from "../core/index.js";
 import { getTypeSignature } from "./type-signature.js";
 
 /**
@@ -51,9 +57,10 @@ function getTypeDocumentation(program: Program, type: Type) {
   }
 
   // Add @doc(...) API docs
-  const apiDocs = getDoc(program, type);
-  if (apiDocs) {
-    docs.push(apiDocs);
+  const apiDocs = getDocData(program, type);
+  // The doc comment is already included above we don't want to duplicate
+  if (apiDocs && apiDocs.source === "@doc") {
+    docs.push(apiDocs.value);
   }
 
   return docs.join("\n\n");

packages/compiler/test/checker/doc-comment.test.ts

@@ -0,0 +1,110 @@
+import { ok, strictEqual } from "assert";
+import { Model, Operation } from "../../core/index.js";
+import { getDoc } from "../../lib/decorators.js";
+import { BasicTestRunner, createTestRunner } from "../../testing/index.js";
+
+describe("compiler: checker: doc comments", () => {
+  let runner: BasicTestRunner;
+  beforeEach(async () => {
+    runner = await createTestRunner();
+  });
+
+  const expectedMainDoc = "This is a doc comment.";
+  const docComment = `/**
+   *  ${expectedMainDoc}
+   */`;
+  function testMainDoc(name: string, code: string) {
+    it(name, async () => {
+      const { target } = await runner.compile(code);
+      ok(target, `Make sure to have @test("target") in code.`);
+
+      strictEqual(getDoc(runner.program, target), expectedMainDoc);
+    });
+  }
+
+  describe("main doc apply to", () => {
+    testMainDoc(
+      "model",
+      `${docComment}
+      @test("target") model Foo {}`
+    );
+
+    testMainDoc(
+      "model property",
+      `
+      model Foo {
+        ${docComment}
+        @test("target") foo: string;
+      }
+    `
+    );
+
+    testMainDoc(
+      "scalar",
+      `${docComment}
+      @test("target") scalar foo;`
+    );
+
+    testMainDoc(
+      "enum",
+      `${docComment}
+      @test("target") enum Foo {}`
+    );
+
+    testMainDoc(
+      "enum memember",
+      `
+      enum Foo {
+        ${docComment}
+        @test("target") foo,
+      }
+    `
+    );
+    testMainDoc(
+      "operation",
+      `${docComment}
+      @test("target") op test(): string;`
+    );
+
+    testMainDoc(
+      "interface",
+      `${docComment}
+      @test("target") interface Foo {}`
+    );
+  });
+
+  it("using @doc() decorator will override the doc comment", async () => {
+    const { Foo } = (await runner.compile(`
+    
+    /**
+     * This is a doc comment.
+     */
+    @doc("This is the actual doc.")
+    @test model Foo {}
+    `)) as { Foo: Model };
+
+    strictEqual(getDoc(runner.program, Foo), "This is the actual doc.");
+  });
+
+  it("using @param in doc comment of operation applies doc on the parameters", async () => {
+    const { addUser } = (await runner.compile(`
+    
+    /**
+     * This is the operation doc.
+     * @param name This is the name param doc.
+     * @param age This is the age param doc.
+     */
+    @test op addUser(name: string, age: string): void;
+    `)) as { addUser: Operation };
+
+    strictEqual(getDoc(runner.program, addUser), "This is the operation doc.");
+    strictEqual(
+      getDoc(runner.program, addUser.parameters.properties.get("name")!),
+      "This is the name param doc."
+    );
+    strictEqual(
+      getDoc(runner.program, addUser.parameters.properties.get("age")!),
+      "This is the age param doc."
+    );
+  });
+});