refactor: work on converting to jsdoc comments (after)

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

@@ -2,6 +2,9 @@
 
 Converts single line or non-JSDoc, multiline comments into JSDoc comments.
 
+Note that this rule is experimental. As usual with fixers, please confirm
+the results before committing.
+
 ## Options
 
 ### `enableFixer`
@@ -45,13 +48,33 @@ Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
 
 Supplying your own value overrides the defaults.
 
+### `contexts`
+
+The contexts which will be checked for preceding content.
+
+Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
+`FunctionExpression`, `TSDeclareFunction`.
+
+### `contextsAfter`
+
+The contexts which will be checked for content on the same line after.
+
+Defaults to an empty array.
+
+### `contextsBeforeAndAfter`
+
+The contexts which will be checked for content before and on the same
+line after.
+
+Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|(N/A)|
 |Recommended|false|
 |Settings|`minLines`, `maxLines`|
-|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
+|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`, `allowedPrefixes`, `contexts`, `contextsAfter`, `contextsBeforeAndAfter`|
 
 ## Failing examples
 

.ncurc.cjs

@@ -8,5 +8,10 @@ module.exports = {
     'decamelize',
     'escape-string-regexp',
     'open-editor',
+
+    // todo[engine:node@>=20]: Can reenable
+    'glob',
+    // todo[engine:node@>=20]: Can reenable
+    'rimraf'
   ],
 };

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

@@ -4,6 +4,9 @@
 
 Converts single line or non-JSDoc, multiline comments into JSDoc comments.
 
+Note that this rule is experimental. As usual with fixers, please confirm
+the results before committing.
+
 <a name="user-content-convert-to-jsdoc-comments-options"></a>
 <a name="convert-to-jsdoc-comments-options"></a>
 ## Options
@@ -57,13 +60,39 @@ Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
 
 Supplying your own value overrides the defaults.
 
+<a name="user-content-convert-to-jsdoc-comments-options-contexts"></a>
+<a name="convert-to-jsdoc-comments-options-contexts"></a>
+### <code>contexts</code>
+
+The contexts which will be checked for preceding content.
+
+Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
+`FunctionExpression`, `TSDeclareFunction`.
+
+<a name="user-content-convert-to-jsdoc-comments-options-contextsafter"></a>
+<a name="convert-to-jsdoc-comments-options-contextsafter"></a>
+### <code>contextsAfter</code>
+
+The contexts which will be checked for content on the same line after.
+
+Defaults to an empty array.
+
+<a name="user-content-convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
+<a name="convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
+### <code>contextsBeforeAndAfter</code>
+
+The contexts which will be checked for content before and on the same
+line after.
+
+Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
+
 |||
 |---|---|
 |Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
 |Tags|(N/A)|
 |Recommended|false|
 |Settings|`minLines`, `maxLines`|
-|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
+|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`, `allowedPrefixes`, `contexts`, `contextsAfter`, `contextsBeforeAndAfter`|
 
 <a name="user-content-convert-to-jsdoc-comments-failing-examples"></a>
 <a name="convert-to-jsdoc-comments-failing-examples"></a>
@@ -134,6 +163,44 @@ export class User {
 // Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
 // "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
 // Message: Block comments should be JSDoc-style.
+
+var a = []; // Test comment
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":["VariableDeclarator"]}]
+// Message: Line comments should be JSDoc-style.
+
+var a = []; // Test comment
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}]}]
+// Message: Line comments should be JSDoc-style.
+
+var a = []; // Test comment
+// Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}]}]
+// Message: Line comments should be JSDoc-style.
+
+// Test comment
+var a = [];
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclaration"]}]
+// Message: Line comments should be JSDoc-style.
+
+var a = []; // Test comment
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclaration"]}]
+// Message: Line comments should be JSDoc-style.
+
+interface B {
+  g: () => string; // Test comment
+}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["TSPropertySignature"]}]
+// Message: Line comments should be JSDoc-style.
+
+class TestClass {
+  public Test: (id: number) => string; // Test comment
+}
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["PropertyDefinition"]}]
+// Message: Line comments should be JSDoc-style.
+
+var a = []; // Test comment
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclarator"]}]
+// Message: Line comments should be JSDoc-style.
 ````
 
 
@@ -175,5 +242,9 @@ function quux () {}
 // @custom-something
 function quux () {}
 // "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"allowedPrefixes":["@custom-"]}]
+
+// Test comment
+var a = [];
+// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":["VariableDeclarator"]}]
 ````
 

package.json

@@ -5,13 +5,13 @@
     "url": "http://gajus.com"
   },
   "dependencies": {
-    "@es-joy/jsdoccomment": "~0.44.0",
+    "@es-joy/jsdoccomment": "~0.45.0",
     "are-docs-informative": "^0.0.2",
     "comment-parser": "1.4.1",
     "debug": "^4.3.5",
     "escape-string-regexp": "^4.0.0",
-    "esquery": "^1.5.0",
-    "parse-imports": "^2.1.0",
+    "esquery": "^1.6.0",
+    "parse-imports": "^2.1.1",
     "semver": "^7.6.2",
     "spdx-expression-parse": "^4.0.0",
     "synckit": "^0.9.0"
@@ -29,7 +29,7 @@
     "@es-joy/jsdoc-eslint-parser": "^0.21.1",
     "@hkdobrev/run-if-changed": "^0.3.1",
     "@semantic-release/commit-analyzer": "^13.0.0",
-    "@semantic-release/github": "^10.0.6",
+    "@semantic-release/github": "^10.1.0",
     "@semantic-release/npm": "^12.0.1",
     "@types/chai": "^4.3.16",
     "@types/debug": "^4.1.12",
@@ -39,35 +39,35 @@
     "@types/json-schema": "^7.0.15",
     "@types/lodash.defaultsdeep": "^4.6.9",
     "@types/mocha": "^10.0.7",
-    "@types/node": "^20.14.9",
+    "@types/node": "^20.14.10",
     "@types/semver": "^7.5.8",
     "@types/spdx-expression-parse": "^3.0.5",
-    "@typescript-eslint/types": "^7.14.1",
+    "@typescript-eslint/types": "^7.16.0",
     "babel-plugin-add-module-exports": "^1.0.4",
-    "babel-plugin-istanbul": "^6.1.1",
+    "babel-plugin-istanbul": "^7.0.0",
     "babel-plugin-transform-import-meta": "^2.2.1",
     "c8": "^10.1.2",
     "camelcase": "^6.3.0",
     "chai": "^4.3.10",
     "cross-env": "^7.0.3",
     "decamelize": "^5.0.1",
-    "eslint": "9.5.0",
+    "eslint": "9.6.0",
     "eslint-config-canonical": "~43.0.13",
     "espree": "^10.1.0",
     "gitdown": "^3.1.5",
     "glob": "^10.4.2",
-    "globals": "^15.6.0",
+    "globals": "^15.8.0",
     "husky": "^9.0.11",
     "jsdoc-type-pratt-parser": "^4.0.0",
     "json-schema": "^0.4.0",
     "lint-staged": "^15.2.7",
     "lodash.defaultsdeep": "^4.6.1",
-    "mocha": "^10.5.2",
+    "mocha": "^10.6.0",
     "open-editor": "^3.0.0",
     "replace": "^1.2.2",
     "rimraf": "^5.0.7",
     "semantic-release": "^24.0.0",
-    "typescript": "5.3.x",
+    "typescript": "5.5.x",
     "typescript-eslint": "^8.0.0-alpha.34"
   },
   "engines": {