Merge pull request #192 from microsoft/octogonz/publish-eslint-plugin-tsdoc

Enable publishing for eslint-plugin-tsdoc

Author: iclanton

README.md

@@ -72,6 +72,7 @@ NOTE: The **@microsoft/tsdoc** library is intended to be incorporated into other
 - Check out the [TSDoc Playground](https://microsoft.github.io/tsdoc/) for a cool interactive demo of TSDoc!  :-)
 - The library [@microsoft/tsdoc](https://www.npmjs.com/package/@microsoft/tsdoc) provides a TSDoc parser that you can use in your own projects.  The source code for this library can be found in the [/tsdoc](./tsdoc/) folder.
 - The [/api-demo](./api-demo/) folder has a small demo project illustrating how to invoke the **@microsoft/tsdoc** library.
+- We also provide an ESLint plugin [eslint-plugin-tsdoc](https://www.npmjs.com/package/eslint-plugin-tsdoc) that you can use to validate your source code.
 - See [Contributing.md](./Contributing.md) for instructions for building, debugging, and contributing to TSDoc.
 - We're using [GitHub issues](https://github.com/Microsoft/tsdoc/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) to discuss the TSDoc specification, library design, and project roadmap.
 

common/changes/eslint-plugin-tsdoc/octogonz-publish-eslint-plugin-tsdoc_2019-11-05-18-08.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "eslint-plugin-tsdoc",
+      "comment": "Initial release of plugin",
+      "type": "minor"
+    }
+  ],
+  "packageName": "eslint-plugin-tsdoc",
+  "email": "bafolts@users.noreply.github.com"
+}

eslint-plugin/README.md

@@ -0,0 +1,64 @@
+# eslint-plugin-tsdoc
+
+This ESLint plugin provides a rule for validating that TypeScript doc comments conform to the
+[TSDoc specification](https://github.com/microsoft/tsdoc).
+
+## Usage
+
+1.  Configure ESLint for your TypeScript project.  See the instructions provided by the
+    [typescript-eslint](https://github.com/typescript-eslint/typescript-eslint) project.
+    You will end up with some dependencies like this:
+
+    **my-project/package.json**  (example)
+    ```ts
+    {
+      "name": "my-project",
+      "version": "1.0.0",
+      "dependencies": {},
+      "devDependencies": {
+        "@typescript-eslint/eslint-plugin": "~2.6.1",
+        "@typescript-eslint/parser": "~2.6.1",
+        "eslint": "~6.6.0",
+        "typescript": "~3.7.2"
+      },
+      "scripts": {
+        "lint": "eslint -f unix \"src/**/*.{ts,tsx}\""
+      }
+    }
+    ```
+
+2.  Add the `eslint-plugin-tsdoc` dependency to your project:
+
+    ```bash
+    $ cd my-project
+    $ npm install --save-dev eslint-plugin-tsdoc
+    ```
+
+3.  In your ESLint config file, add the `"eslint-plugin-tsdoc"` package to your `plugins` field,
+    and enable the `"tsdoc/syntax"` rule.  For example:
+
+    **my-project/.eslintrc.js** (example)
+    ```ts
+    module.exports =  {
+      plugins: [
+        "@typescript-eslint/eslint-plugin",
+        "eslint-plugin-tsdoc"
+      ],
+      extends:  [
+        'plugin:@typescript-eslint/recommended'
+      ],
+      parser:  '@typescript-eslint/parser',
+      parserOptions: {
+        project: "./tsconfig.json",
+        tsconfigRootDir: __dirname,
+        ecmaVersion: 2018,
+        sourceType: "module"
+      },
+      rules: {
+        "tsdoc/syntax": "warn"
+      }
+    };
+    ```
+
+This package is maintained by the TSDoc project.  If you have questions or feedback, please
+[let us know](https://github.com/microsoft/tsdoc/issues)!

eslint-plugin/package.json

@@ -1,9 +1,25 @@
 {
   "name": "eslint-plugin-tsdoc",
-  "version": "0.1.0",
-  "description": "eslint plugin for tsdoc",
-  "private": false,
+  "version": "0.0.0",
+  "description": "An ESLint plugin that validates TypeScript doc comments",
+  "keywords": [
+    "TypeScript",
+    "documentation",
+    "doc",
+    "comments",
+    "JSDoc",
+    "TSDoc",
+    "ESLint",
+    "plugin"
+  ],
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/tsdoc/tree/master/eslint-plugin"
+  },
+  "homepage": "https://github.com/microsoft/tsdoc",
+  "main": "lib/index.js",
+  "typings": "lib/index.d.ts",
   "scripts": {
     "build": "node ./build.js",
     "lint": "eslint -f unix \"src/**/*.{ts,tsx}\"",

eslint-plugin/src/index.ts

@@ -14,15 +14,18 @@ interface IPlugin {
     rules: {[x: string]: eslint.Rule.RuleModule};
 }
 
-export const plugin: IPlugin = {
+const plugin: IPlugin = {
   rules: {
-    "tsdoc-comments": {
+    // NOTE: The actual ESLint rule name will be "tsdoc/syntax".  It is calculated by deleting "eslint-plugin-"
+    // from the NPM package name, and then appending this string.
+    "syntax": {
       meta: {
         messages: messageIds,
         type: "problem",
         docs: {
-          description: "Validates tsdoc comments",
-          category: "Typescript",
+          description: "Validates that TypeScript documentation comments conform to the TSDoc standard",
+          category: "Stylistic Issues",
+          // This package is experimental
           recommended: false,
           url: "https://github.com/microsoft/tsdoc"
         }
@@ -31,16 +34,13 @@ export const plugin: IPlugin = {
         const tsDocParser: TSDocParser = new TSDocParser();
         const sourceCode: eslint.SourceCode = context.getSourceCode();
         const checkCommentBlocks: (node: ESTree.Node) => void = function (node: ESTree.Node) {
-          const commentBlocks: ESTree.Comment[] = sourceCode.getCommentsBefore(node).filter(function (comment: ESTree.Comment) {
-            return comment.type === "Block";
-          });
-          if (commentBlocks.length > 0) {
-            const commentBlock: ESTree.Comment = commentBlocks[0];
-            const commentString: string = "/*" + commentBlock.value + "*/";
+          const commentToken: eslint.AST.Token | null = sourceCode.getJSDocComment(node);
+          if (commentToken) {
+            const commentString: string = "/*" + commentToken.value + "*/";
             const results: ParserMessageLog = tsDocParser.parseString(commentString).log;
             for (const message of results.messages) {
               context.report({
-                node: node,
+                loc: commentToken.loc,
                 messageId: message.messageId,
                 data: {
                   unformattedText: message.unformattedText
@@ -58,3 +58,5 @@ export const plugin: IPlugin = {
     }
   }
 }
+
+export = plugin;

eslint-plugin/src/tests/index.ts

@@ -1,13 +1,13 @@
 
 import { RuleTester } from "eslint";
-import { plugin } from "../index";
+import * as plugin from "../index";
 
 const ruleTester: RuleTester = new RuleTester({
   env: {
     es6: true
   }
 });
-ruleTester.run("tsdoc-comments", plugin.rules["tsdoc-comments"], {
+ruleTester.run("syntax", plugin.rules.syntax, {
   valid: [
     "/**\nA great function!\n */\nfunction foobar() {}\n",
     "/**\nA great class!\n */\nclass FooBar {}\n"

rush.json

@@ -153,7 +153,7 @@
   //     "tools",      // non-shipping projects that are part of the developer toolchain
   //     "prototypes"  // experiments that should mostly be ignored by the review process
   //   ],
-  // 
+  //
   //   /**
   //    * A list of NPM package scopes that will be excluded from review.
   //    * We recommend to exclude TypeScript typings (the "@types" scope), because
@@ -269,7 +269,7 @@
     //    * The folder name for this variant.
     //    */
     //   "variantName": "old-sdk",
-    // 
+    //
     //   /**
     //    * An informative description
     //    */
@@ -308,19 +308,19 @@
     //    * The NPM package name of the project (must match package.json)
     //    */
     //   "packageName": "my-app",
-    // 
+    //
     //   /**
     //    * The path to the project folder, relative to the rush.json config file.
     //    */
     //   "projectFolder": "apps/my-app",
-    // 
+    //
     //   /**
     //    * An optional category for usage in the "browser-approved-packages.json"
     //    * and "nonbrowser-approved-packages.json" files.  The value must be one of the
     //    * strings from the "reviewCategories" defined above.
     //    */
     //   "reviewCategory": "production",
-    // 
+    //
     //   /**
     //    * A list of local projects that appear as devDependencies for this project, but cannot be
     //    * locally linked because it would create a cyclic dependency; instead, the last published
@@ -329,40 +329,40 @@
     //   "cyclicDependencyProjects": [
     //     // "my-toolchain"
     //   ],
-    // 
+    //
     //   /**
     //    * If true, then this project will be ignored by the "rush check" command.
     //    * The default value is false.
     //    */
     //   // "skipRushCheck": false,
-    // 
+    //
     //   /**
     //    * A flag indicating that changes to this project will be published to npm, which affects
     //    * the Rush change and publish workflows. The default value is false.
     //    * NOTE: "versionPolicyName" and "shouldPublish" are alternatives; you cannot specify them both.
     //    */
     //   // "shouldPublish": false,
-    // 
+    //
     //   /**
     //    * An optional version policy associated with the project.  Version policies are defined
     //    * in "version-policies.json" file.  See the "rush publish" documentation for more info.
     //    * NOTE: "versionPolicyName" and "shouldPublish" are alternatives; you cannot specify them both.
     //    */
     //   // "versionPolicyName": ""
     // },
-    // 
+    //
     // {
     //   "packageName": "my-controls",
     //   "projectFolder": "libraries/my-controls",
     //   "reviewCategory": "production"
     // },
-    // 
+    //
     // {
     //   "packageName": "my-toolchain",
     //   "projectFolder": "tools/my-toolchain",
     //   "reviewCategory": "tools"
     // }
-    
+
     {
       "packageName": "api-demo",
       "projectFolder": "api-demo"
@@ -378,7 +378,8 @@
     },
     {
       "packageName": "eslint-plugin-tsdoc",
-      "projectFolder": "eslint-plugin"
+      "projectFolder": "eslint-plugin",
+      "shouldPublish": true
     }
   ]
 }