Merge pull request #195 from microsoft/octogonz/eliminate-internal-api

eslint-plugin-tsdoc: Avoid importing internal API

Author: octogonz

common/changes/@microsoft/tsdoc/octogonz-eliminate-internal-api_2019-11-09-05-45.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Add new API TSDocConfiguration.allTsdocMessageIds",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}

common/changes/eslint-plugin-tsdoc/octogonz-eliminate-internal-api_2019-11-09-05-45.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "eslint-plugin-tsdoc",
+      "comment": "Improve lint rule to check every doc comment in a source file",
+      "type": "patch"
+    }
+  ],
+  "packageName": "eslint-plugin-tsdoc",
+  "email": "4673363+octogonz@users.noreply.github.com"
+}

eslint-plugin/src/index.ts

@@ -1,25 +1,25 @@
 
 import {
-  ParserMessageLog,
   TSDocParser,
   TextRange,
   TSDocConfiguration,
   StandardTags,
   TSDocTagDefinition,
-  TSDocTagSyntaxKind
+  TSDocTagSyntaxKind,
+  ParserContext
 } from "@microsoft/tsdoc";
-import { allTsdocMessageIds } from "@microsoft/tsdoc/lib/parser/TSDocMessageId";
 import * as eslint from "eslint";
 import * as ESTree from "estree";
 
 const messageIds: {[x: string]: string} = {};
 
-allTsdocMessageIds.forEach((messageId: string) => {
+const defaultTSDocConfiguration: TSDocConfiguration = new TSDocConfiguration()
+defaultTSDocConfiguration.allTsdocMessageIds.forEach((messageId: string) => {
   messageIds[messageId] = `${messageId}: {{ unformattedText }}`;
 });
 
 interface IPlugin {
-    rules: {[x: string]: eslint.Rule.RuleModule};
+  rules: {[x: string]: eslint.Rule.RuleModule};
 }
 
 const plugin: IPlugin = {
@@ -64,11 +64,27 @@ const plugin: IPlugin = {
 
         const sourceCode: eslint.SourceCode = context.getSourceCode();
         const checkCommentBlocks: (node: ESTree.Node) => void = function (node: ESTree.Node) {
-          const commentToken: eslint.AST.Token | null = sourceCode.getJSDocComment(node);
-          if (commentToken) {
-            const textRange: TextRange = TextRange.fromStringRange(sourceCode.text, commentToken.range[0], commentToken.range[1]);
-            const results: ParserMessageLog = tsdocParser.parseRange(textRange).log;
-            for (const message of results.messages) {
+          for (const comment of sourceCode.getAllComments()) {
+            if (comment.type !== "Block") {
+              continue;
+            }
+            if (!comment.range) {
+              continue;
+            }
+
+            const textRange: TextRange = TextRange.fromStringRange(sourceCode.text, comment.range[0], comment.range[1]);
+
+            // Smallest comment is "/***/"
+            if (textRange.length < 5) {
+              continue;
+            }
+            // Make sure it starts with "/**"
+            if (textRange.buffer[textRange.pos + 2] !== '*') {
+              continue;
+            }
+
+            const parserContext: ParserContext = tsdocParser.parseRange(textRange);
+            for (const message of parserContext.log.messages) {
               context.report({
                 loc: {
                   start: sourceCode.getLocFromIndex(message.textRange.pos),
@@ -84,8 +100,7 @@ const plugin: IPlugin = {
         }
 
         return {
-          ClassDeclaration: checkCommentBlocks,
-          FunctionDeclaration: checkCommentBlocks
+          Program: checkCommentBlocks
         };
       }
     }

tsdoc/src/configuration/TSDocConfiguration.ts

@@ -3,7 +3,7 @@ import { TSDocTagDefinition } from './TSDocTagDefinition';
 import { TSDocValidationConfiguration } from './TSDocValidationConfiguration';
 import { DocNodeManager } from './DocNodeManager';
 import { BuiltInDocNodes } from '../nodes/BuiltInDocNodes';
-import { TSDocMessageId, allTsdocMessageIds } from '../parser/TSDocMessageId';
+import { TSDocMessageId, allTsdocMessageIds, allTsdocMessageIdsSet } from '../parser/TSDocMessageId';
 
 /**
  * Configuration for the TSDocParser.
@@ -170,7 +170,19 @@ export class TSDocConfiguration {
    * of the TSDoc parser, we may provide a way to register custom message identifiers.
    */
   public isKnownMessageId(messageId: TSDocMessageId | string): boolean {
-    return allTsdocMessageIds.has(messageId);
+    return allTsdocMessageIdsSet.has(messageId);
+  }
+
+  /**
+   * Returns the list of {@link TSDocMessageId} strings that are implemented by this release of the TSDoc parser.
+   *
+   * @privateRemarks
+   *
+   * Why this API is associated with TSDocConfiguration:  In the future, if we enable support for custom extensions
+   * of the TSDoc parser, we may provide a way to register custom message identifiers.
+   */
+  public get allTsdocMessageIds(): ReadonlyArray<TSDocMessageId> {
+    return allTsdocMessageIds as ReadonlyArray<TSDocMessageId>;
   }
 
   private _requireTagToBeDefined(tagDefinition: TSDocTagDefinition): void {

tsdoc/src/parser/TSDocMessageId.ts

@@ -336,8 +336,8 @@ export const enum TSDocMessageId {
   CodeSpanMissingDelimiter = 'tsdoc-code-span-missing-delimiter'
 }
 
-// Exposed via ParserMessage.isValidMessageId()
-export const allTsdocMessageIds: Set<string> = new Set<string>([
+// Exposed via TSDocConfiguration.allTsdocMessageIds()
+export const allTsdocMessageIds: string[] = [
   'tsdoc-comment-not-found',
   'tsdoc-comment-missing-opening-delimiter',
   'tsdoc-comment-missing-closing-delimiter',
@@ -398,4 +398,7 @@ export const allTsdocMessageIds: Set<string> = new Set<string>([
   'tsdoc-code-fence-closing-syntax',
   'tsdoc-code-span-empty',
   'tsdoc-code-span-missing-delimiter'
-]);
+];
+allTsdocMessageIds.sort();
+
+export const allTsdocMessageIdsSet: ReadonlySet<string> = new Set<string>(allTsdocMessageIds);

tsdoc/src/parser/TextRange.ts

@@ -62,6 +62,15 @@ export class TextRange {
     return new TextRange(buffer, pos, end);
   }
 
+  /**
+   * Returns the length of the text range.
+   * @remarks
+   * This value is calculated as the `end` property minus the `pos` property.
+   */
+  public get length(): number {
+    return this.end - this.pos;
+  }
+
   /**
    * Constructs a TextRange that corresponds to a different range of an existing buffer.
    */