Skip to content

Latest commit

 

History

History
250 lines (186 loc) · 8.79 KB

convert-to-jsdoc-comments.md

File metadata and controls

250 lines (186 loc) · 8.79 KB
Raw

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.

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

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, 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", {"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.

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.

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", {"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-"]}]

// Test comment
var a = [];
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":["VariableDeclarator"]}]