Add a new message "ae-undocumented" to support logging of undocumente…

…d API items
microsoft · Sep 28, 2023 · ee4e53f · ee4e53f
1 parent 328826c
commit ee4e53f
Show file tree

Hide file tree

Showing 6 changed files with 36 additions and 5 deletions.
diff --git a/apps/api-extractor/src/api/ExtractorMessageId.ts b/apps/api-extractor/src/api/ExtractorMessageId.ts
@@ -17,6 +17,25 @@ export const enum ExtractorMessageId {
    */
   ExtraReleaseTag = 'ae-extra-release-tag',
 
+  /**
+   * "Missing documentation for ___."
+   * @remarks
+   * The `ae-undocumented` message is only generated if the API report feature is enabled.
+   *
+   * Because the API report file already annotates undocumented items with `// (undocumented)`,
+   * the `ae-undocumented` message is not logged by default.  To see it, add a setting such as:
+   * ```json
+   * "messages": {
+   *   "extractorMessageReporting": {
+   *     "ae-undocumented": {
+   *       "logLevel": "warning"
+   *     }
+   *   }
+   *  }
+   * ```
+   */
+  Undocumented = 'ae-undocumented',
+
   /**
    * "This symbol has another declaration with a different release tag."
    */
@@ -106,6 +125,7 @@ export const enum ExtractorMessageId {
 
 export const allExtractorMessageIds: Set<string> = new Set<string>([
   'ae-extra-release-tag',
+  'ae-undocumented',
   'ae-different-release-tags',
   'ae-incompatible-release-tags',
   'ae-missing-release-tag',

diff --git a/apps/api-extractor/src/collector/ApiItemMetadata.ts b/apps/api-extractor/src/collector/ApiItemMetadata.ts
@@ -76,7 +76,7 @@ export class ApiItemMetadata {
   public tsdocComment: tsdoc.DocComment | undefined;
 
   // Assigned by DocCommentEnhancer
-  public needsDocumentation: boolean = true;
+  public undocumented: boolean = true;
 
   public docCommentEnhancerVisitorState: VisitorState = VisitorState.Unvisited;
 

diff --git a/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts b/apps/api-extractor/src/enhancers/DocCommentEnhancer.ts
@@ -73,7 +73,7 @@ export class DocCommentEnhancer {
       // Constructors always do pretty much the same thing, so it's annoying to require people to write
       // descriptions for them.  Instead, if the constructor lacks a TSDoc summary, then API Extractor
       // will auto-generate one.
-      metadata.needsDocumentation = false;
+      metadata.undocumented = false;
 
       // The class that contains this constructor
       const classDeclaration: AstDeclaration = astDeclaration.parent!;
@@ -135,12 +135,12 @@ export class DocCommentEnhancer {
 
     if (metadata.tsdocComment) {
       // Require the summary to contain at least 10 non-spacing characters
-      metadata.needsDocumentation = !tsdoc.PlainTextEmitter.hasAnyTextContent(
+      metadata.undocumented = !tsdoc.PlainTextEmitter.hasAnyTextContent(
         metadata.tsdocComment.summarySection,
         10
       );
     } else {
-      metadata.needsDocumentation = true;
+      metadata.undocumented = true;
     }
   }
 

diff --git a/apps/api-extractor/src/generators/ApiReportGenerator.ts b/apps/api-extractor/src/generators/ApiReportGenerator.ts
@@ -20,6 +20,7 @@ import { AstNamespaceImport } from '../analyzer/AstNamespaceImport';
 import type { AstEntity } from '../analyzer/AstEntity';
 import type { AstModuleExportInfo } from '../analyzer/AstModule';
 import { SourceFileLocationFormatter } from '../analyzer/SourceFileLocationFormatter';
+import { ExtractorMessageId } from '../api/ExtractorMessageId';
 
 export class ApiReportGenerator {
   private static _trimSpacesRegExp: RegExp = / +$/gm;
@@ -522,8 +523,14 @@ export class ApiReportGenerator {
         }
       }
 
-      if (apiItemMetadata.needsDocumentation) {
+      if (apiItemMetadata.undocumented) {
         footerParts.push('(undocumented)');
+
+        collector.messageRouter.addAnalyzerIssue(
+          ExtractorMessageId.Undocumented,
+          `Missing documentation for "${astDeclaration.astSymbol.localName}".`,
+          astDeclaration
+        );
       }
 
       if (footerParts.length > 0) {

diff --git a/apps/api-extractor/src/schemas/api-extractor-defaults.json b/apps/api-extractor/src/schemas/api-extractor-defaults.json
@@ -69,6 +69,9 @@
         "logLevel": "warning",
         "addToApiReportFile": true
       },
+      "ae-undocumented": {
+        "logLevel": "none"
+      },
       "ae-unresolved-inheritdoc-reference": {
         "logLevel": "warning",
         "addToApiReportFile": true

diff --git a/common/reviews/api/api-extractor.api.md b/common/reviews/api/api-extractor.api.md
@@ -144,6 +144,7 @@ export const enum ExtractorMessageId {
     PreapprovedBadReleaseTag = "ae-preapproved-bad-release-tag",
     PreapprovedUnsupportedType = "ae-preapproved-unsupported-type",
     SetterWithDocs = "ae-setter-with-docs",
+    Undocumented = "ae-undocumented",
     UnresolvedInheritDocBase = "ae-unresolved-inheritdoc-base",
     UnresolvedInheritDocReference = "ae-unresolved-inheritdoc-reference",
     UnresolvedLink = "ae-unresolved-link",