Fix the bug

Author: octogonz

apps/api-extractor/src/analyzer/Span.ts

@@ -16,19 +16,39 @@ enum IndentDocCommentState {
   /**
    * `indentDocComment` was not requested for this subtree.
    */
-  Inactive,
+  Inactive = 0,
   /**
    * `indentDocComment` was requested and we are looking for the opening `/` `*`
    */
-  AwaitingOpenDelimiter,
+  AwaitingOpenDelimiter = 1,
   /**
    * `indentDocComment` was requested and we are looking for the closing `*` `/`
    */
-  AwaitingCloseDelimiter,
+  AwaitingCloseDelimiter = 2,
   /**
    * `indentDocComment` was requested and we have finished indenting the comment.
    */
-  Done
+  Done = 3
+}
+
+/**
+ * Choices for SpanModification.indentDocComment.
+ */
+export enum IndentDocCommentScope {
+  /**
+   * Do not detect and indent comments.
+   */
+  None = 0,
+
+  /**
+   * Look for one doc comment in the {@link Span.prefix} text only.
+   */
+  PrefixOnly = 1,
+
+  /**
+   * Look for one doc comment potentially distributed across the Span and its children.
+   */
+  SpanAndChildren = 2
 }
 
 /**
@@ -61,8 +81,13 @@ export class SpanModification {
 
   /**
    * If true, then getModifiedText() will search for a "/*" doc comment in this span and indent it.
+   *
+   * @remarks
+   * This feature is selectively enabled because (1) we do not want to accidentally `/*` appearing
+   * in a string literal or other expression that is not a comment, and (2) parsing comments is potentially
+   * expensive.
    */
-  public indentDocComment: boolean = false;
+  public indentDocComment: IndentDocCommentScope = IndentDocCommentScope.None;
 
   private readonly _span: Span;
   private _prefix: string | undefined;
@@ -105,7 +130,9 @@ export class SpanModification {
     this.sortKey = undefined;
     this._prefix = undefined;
     this._suffix = undefined;
-    this.indentDocComment = this._span.kind === ts.SyntaxKind.JSDocComment;
+    if (this._span.kind === ts.SyntaxKind.JSDocComment) {
+      this.indentDocComment = IndentDocCommentScope.SpanAndChildren;
+    }
   }
 
   /**
@@ -450,36 +477,23 @@ export class Span {
    * Recursive implementation of `getModifiedText()` and `writeModifiedText()`.
    */
   private _writeModifiedText(options: IWriteModifiedTextOptions): void {
-    if (this.modification.indentDocComment) {
-      if (options.indentDocCommentState !== IndentDocCommentState.Inactive) {
-        throw new InternalError('indentDocComment cannot be nested');
-      }
-      options.indentDocCommentState = IndentDocCommentState.AwaitingOpenDelimiter;
-    }
-
+    // Apply indentation based on "{" and "}"
     if (this.prefix === '{') {
       options.writer.increaseIndent();
     } else if (this.prefix === '}') {
       options.writer.decreaseIndent();
     }
 
-    this._writeModifiedTextContent(options);
-
-    if (this.modification.indentDocComment) {
-      if (options.indentDocCommentState === IndentDocCommentState.AwaitingCloseDelimiter) {
-        throw new InternalError('missing "*/" delimiter for comment block');
-      }
-      options.indentDocCommentState = IndentDocCommentState.Inactive;
+    if (this.modification.indentDocComment !== IndentDocCommentScope.None) {
+      this._beginIndentDocComment(options);
     }
-  }
 
-  /**
-   * This is a helper for `_writeModifiedText()`.  `_writeModifiedText()` configures indentation
-   * whereas `_writeModifiedTextContent()` does the actual writing.
-   */
-  private _writeModifiedTextContent(options: IWriteModifiedTextOptions): void {
     this._write(this.modification.prefix, options);
 
+    if (this.modification.indentDocComment === IndentDocCommentScope.PrefixOnly) {
+      this._endIndentDocComment(options);
+    }
+
     let sortedSubset: Span[] | undefined;
 
     if (!this.modification.omitChildren) {
@@ -573,6 +587,24 @@ export class Span {
         }
       }
     }
+
+    if (this.modification.indentDocComment === IndentDocCommentScope.SpanAndChildren) {
+      this._endIndentDocComment(options);
+    }
+  }
+
+  private _beginIndentDocComment(options: IWriteModifiedTextOptions): void {
+    if (options.indentDocCommentState !== IndentDocCommentState.Inactive) {
+      throw new InternalError('indentDocComment cannot be nested');
+    }
+    options.indentDocCommentState = IndentDocCommentState.AwaitingOpenDelimiter;
+  }
+
+  private _endIndentDocComment(options: IWriteModifiedTextOptions): void {
+    if (options.indentDocCommentState === IndentDocCommentState.AwaitingCloseDelimiter) {
+      throw new InternalError('missing "*/" delimiter for comment block');
+    }
+    options.indentDocCommentState = IndentDocCommentState.Inactive;
   }
 
   /**

apps/api-extractor/src/generators/DtsRollupGenerator.ts

@@ -9,7 +9,7 @@ import { ReleaseTag } from '@microsoft/api-extractor-model';
 
 import { Collector } from '../collector/Collector';
 import { TypeScriptHelpers } from '../analyzer/TypeScriptHelpers';
-import { Span, SpanModification } from '../analyzer/Span';
+import { IndentDocCommentScope, Span, SpanModification } from '../analyzer/Span';
 import { AstImport } from '../analyzer/AstImport';
 import { CollectorEntity } from '../collector/CollectorEntity';
 import { AstDeclaration } from '../analyzer/AstDeclaration';
@@ -333,7 +333,7 @@ export class DtsRollupGenerator {
             if (!/\r?\n\s*$/.test(originalComment)) {
               originalComment += '\n';
             }
-            span.modification.indentDocComment = true;
+            span.modification.indentDocComment = IndentDocCommentScope.PrefixOnly;
             span.modification.prefix = originalComment + span.modification.prefix;
           }
         }

build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/api-extractor-scenarios.api.json

@@ -355,7 +355,7 @@
         {
           "kind": "Variable",
           "canonicalReference": "api-extractor-scenarios!exampleD:var",
-          "docComment": "/**\n * Outer description\n */\n",
+          "docComment": "/**\n * Outer description\n *\n * @public\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",

build-tests/api-extractor-scenarios/etc/test-outputs/spanSorting/rollup.d.ts

@@ -37,6 +37,7 @@ export declare class ExampleC {
 
 /**
  * Outer description
+ * @public
  */
 export declare const exampleD: (o: {
     /**

build-tests/api-extractor-scenarios/src/spanSorting/index.ts

@@ -42,6 +42,7 @@ export class ExampleC {
 
 /**
  * Outer description
+ * @public
  */
 export const exampleD = (o: {
   /**