feat: new rule convert-to-jsdoc-comments; fixes #1002

.README/rules/convert-to-jsdoc-comments.md

@@ -0,0 +1,62 @@
+# `convert-to-jsdoc-comments`
+
+Converts single line or non-JSDoc, multiline comments into JSDoc comments.
+
+## Options
+
+### `enableFixer`
+
+Set to `false` to disable fixing.
+
+### `lineOrBlockStyle`
+
+What style of comments to which to apply JSDoc conversion.
+
+- `block` - Applies to block-style comments (`/* ... */`)
+- `line` - Applies to line-style comments (`// ...`)
+- `both` - Applies to both block and line-style comments
+
+Defaults to `both`.
+
+### `enforceJsdocLineStyle`
+
+What policy to enforce on the conversion of non-JSDoc comments without
+line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
+be converted to `multi` style JSDoc comments.)
+
+- `multi` - Convert to multi-line style
+```js
+/**
+ * Some text
+ */
+```
+- `single` - Convert to single-line style
+```js
+/** Some text */
+```
+
+Defaults to `multi`.
+
+### `allowedPrefixes`
+
+An array of prefixes to allow at the beginning of a comment.
+
+Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
+
+Supplying your own value overrides the defaults.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|(N/A)|
+|Recommended|false|
+|Settings|`minLines`, `maxLines`|
+|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
+
+## Failing examples
+
+<!-- assertions-failing convertToJsdocComments -->
+
+## Passing examples
+
+<!-- assertions-passing convertToJsdocComments -->

docs/rules/convert-to-jsdoc-comments.md

@@ -0,0 +1,179 @@
+<a name="user-content-convert-to-jsdoc-comments"></a>
+<a name="convert-to-jsdoc-comments"></a>
+# <code>convert-to-jsdoc-comments</code>
+
+Converts single line or non-JSDoc, multiline comments into JSDoc comments.
+
+<a name="user-content-convert-to-jsdoc-comments-options"></a>
+<a name="convert-to-jsdoc-comments-options"></a>
+## Options
+
+<a name="user-content-convert-to-jsdoc-comments-options-enablefixer"></a>
+<a name="convert-to-jsdoc-comments-options-enablefixer"></a>
+### <code>enableFixer</code>
+
+Set to `false` to disable fixing.
+
+<a name="user-content-convert-to-jsdoc-comments-options-lineorblockstyle"></a>
+<a name="convert-to-jsdoc-comments-options-lineorblockstyle"></a>
+### <code>lineOrBlockStyle</code>
+
+What style of comments to which to apply JSDoc conversion.
+
+- `block` - Applies to block-style comments (`/* ... */`)
+- `line` - Applies to line-style comments (`// ...`)
+- `both` - Applies to both block and line-style comments
+
+Defaults to `both`.
+
+<a name="user-content-convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
+<a name="convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
+### <code>enforceJsdocLineStyle</code>
+
+What policy to enforce on the conversion of non-JSDoc comments without
+line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
+be converted to `multi` style JSDoc comments.)
+
+- `multi` - Convert to multi-line style
+```js
+/**
+ * Some text
+ */
+```
+- `single` - Convert to single-line style
+```js
+/** Some text */
+```
+
+Defaults to `multi`.
+
+<a name="user-content-convert-to-jsdoc-comments-options-allowedprefixes"></a>
+<a name="convert-to-jsdoc-comments-options-allowedprefixes"></a>
+### <code>allowedPrefixes</code>
+
+An array of prefixes to allow at the beginning of a comment.
+
+Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
+
+Supplying your own value overrides the defaults.
+
+|||
+|---|---|
+|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
+|Tags|(N/A)|
+|Recommended|false|
+|Settings|`minLines`, `maxLines`|
+|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
+
+<a name="user-content-convert-to-jsdoc-comments-failing-examples"></a>
+<a name="convert-to-jsdoc-comments-failing-examples"></a>
+## Failing examples
+
+The following patterns are considered problems:
+
+````js
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
+// Message: Line comments should be JSDoc-style.
+
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contexts":[{"context":"FunctionDeclaration","inlineCommentBlock":true}]}]
+// Message: Line comments should be JSDoc-style.
+
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enableFixer":false,"enforceJsdocLineStyle":"single"}]
+// Message: Line comments should be JSDoc-style.
+
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line","enforceJsdocLineStyle":"single"}]
+// Message: Line comments should be JSDoc-style.
+
+/* A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
+// Message: Block comments should be JSDoc-style.
+
+/* A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block","enforceJsdocLineStyle":"single"}]
+// Message: Block comments should be JSDoc-style.
+
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
+// Message: Line comments should be JSDoc-style.
+
+// A single line comment
+function quux () {}
+// Message: Line comments should be JSDoc-style.
+
+/* A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
+// Message: Block comments should be JSDoc-style.
+
+// Single line comment
+function quux() {
+
+}
+// Settings: {"jsdoc":{"structuredTags":{"see":{"name":false,"required":["name"]}}}}
+// Message: Cannot add "name" to `require` with the tag's `name` set to `false`
+
+/* Entity to represent a user in the system. */
+@Entity('users', getVal())
+export class User {
+}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
+// Message: Block comments should be JSDoc-style.
+
+/* A single line comment */ function quux () {}
+// Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
+// Message: Block comments should be JSDoc-style.
+````
+
+
+
+<a name="user-content-convert-to-jsdoc-comments-passing-examples"></a>
+<a name="convert-to-jsdoc-comments-passing-examples"></a>
+## Passing examples
+
+The following patterns are not considered problems:
+
+````js
+/** A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
+
+/** A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
+
+/** A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line"}]
+
+/** A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block"}]
+
+/* A single line comment */
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line","enforceJsdocLineStyle":"single"}]
+
+// A single line comment
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block","enforceJsdocLineStyle":"single"}]
+
+// @ts-expect-error
+function quux () {}
+
+// @custom-something
+function quux () {}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"allowedPrefixes":["@custom-"]}]
+````
+

package.json

@@ -5,7 +5,7 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.43.1",
+    "@es-joy/jsdoccomment": "~0.44.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.3.5",

src/bin/generateRule.js

@@ -121,7 +121,7 @@ export default iterateJsdoc(({
     await fs.writeFile(ruleTestPath, ruleTestTemplate);
   }
 
-  const ruleReadmeTemplate = `### \`${ruleName}\`
+  const ruleReadmeTemplate = `# \`${ruleName}\`
 
 |||
 |---|---|

src/index.js

@@ -9,6 +9,7 @@ import checkSyntax from './rules/checkSyntax.js';
 import checkTagNames from './rules/checkTagNames.js';
 import checkTypes from './rules/checkTypes.js';
 import checkValues from './rules/checkValues.js';
+import convertToJsdocComments from './rules/convertToJsdocComments.js';
 import emptyTags from './rules/emptyTags.js';
 import implementsOnClasses from './rules/implementsOnClasses.js';
 import importsAsDependencies from './rules/importsAsDependencies.js';
@@ -81,6 +82,7 @@ const index = {
     'check-tag-names': checkTagNames,
     'check-types': checkTypes,
     'check-values': checkValues,
+    'convert-to-jsdoc-comments': convertToJsdocComments,
     'empty-tags': emptyTags,
     'implements-on-classes': implementsOnClasses,
     'imports-as-dependencies': importsAsDependencies,
@@ -153,6 +155,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
       'jsdoc/check-tag-names': warnOrError,
       'jsdoc/check-types': warnOrError,
       'jsdoc/check-values': warnOrError,
+      'jsdoc/convert-to-jsdoc-comments': 'off',
       'jsdoc/empty-tags': warnOrError,
       'jsdoc/implements-on-classes': warnOrError,
       'jsdoc/imports-as-dependencies': 'off',