Merge pull request #4370 from microsoft/octogonz/ae-undocumented

[api-extractor] Add a new message "ae-undocumented"

Author: octogonz

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',

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;
 

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;
     }
   }
 

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) {

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

build-tests/install-test-workspace/workspace/common/pnpm-lock.yaml

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "comment": "Add a new message \"ae-undocumented\" to support logging of undocumented API items",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/api-extractor"
+}

common/changes/@microsoft/api-extractor/octogonz-ae-undocumented_2023-09-28-20-00.json

@@ -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",

common/reviews/api/api-extractor.api.md

@@ -53,7 +53,7 @@ export interface IInstallManagerOptions {
   recheckShrinkwrap: boolean;
 
   /**
-   * Do not attempt to access the network. Report an error if the required dependencies 
+   * Do not attempt to access the network. Report an error if the required dependencies
    * cannot be obtained from the local cache.
    */
   offline: boolean;