Skip to content

convert-to-jsdoc-comments.md

Latest commit

 

History

History
265 lines (194 loc) · 9.38 KB

convert-to-jsdoc-comments.md

File metadata and controls

265 lines (194 loc) · 9.38 KB

convert-to-jsdoc-comments

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.

Fixer

Converts comments into JSDoc comments.

Options

A single options object has the following properties.

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.

contexts

The contexts array which will be checked for preceding content.

Can either be strings or an object with a context string and an optional, default false inlineCommentBlock boolean.

Defaults to ArrowFunctionExpression, FunctionDeclaration, FunctionExpression, TSDeclareFunction.

contextsAfter

The contexts array which will be checked for content on the same line after.

Can either be strings or an object with a context string and an optional, default false inlineCommentBlock boolean.

Defaults to an empty array.

contextsBeforeAndAfter

The contexts array which will be checked for content before and on the same line after.

Can either be strings or an object with a context string and an optional, default false inlineCommentBlock boolean.

Defaults to VariableDeclarator, TSPropertySignature, PropertyDefinition.

enableFixer

Set to false to disable fixing.

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
/**
 * Some text
 */
  • single - Convert to single-line style
/** Some text */

Defaults to multi.

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.
Context ArrowFunctionExpression, FunctionDeclaration, FunctionExpression
Tags (N/A)
Recommended false
Settings minLines, maxLines
Options enableFixer, enforceJsdocLineStyle, lineOrBlockStyle, allowedPrefixes, contexts, contextsAfter, contextsBeforeAndAfter

Failing examples

The following patterns are considered problems:

// 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", {"enforceJsdocLineStyle":"single","lineOrBlockStyle":"line"}]
// 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", {"enforceJsdocLineStyle":"single","lineOrBlockStyle":"block"}]
// 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":{"maxLines":0,"minLines":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", {"contextsAfter":["VariableDeclarator"],"contextsBeforeAndAfter":[]}]
// Message: Line comments should be JSDoc-style.

var a = []; // Test comment
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}],"contextsBeforeAndAfter":[]}]
// Message: Line comments should be JSDoc-style.

var a = []; // Test comment
// Settings: {"jsdoc":{"maxLines":0,"minLines":0}}
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}],"contextsBeforeAndAfter":[]}]
// 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.

Passing examples

The following patterns are not considered problems:

/** 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", {"enforceJsdocLineStyle":"single","lineOrBlockStyle":"line"}]

// A single line comment
function quux () {}
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single","lineOrBlockStyle":"block"}]

// @ts-expect-error
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", {"contextsAfter":["VariableDeclarator"],"contextsBeforeAndAfter":[]}]