preface

I’ve been working on a file comment for the front-end code, simply recording how to use jsDoc and the configuration information (if you have esLint configured in your project).

What is the jsDoc

JsDoc is a tool that generates API documentation for JavaScript applications or modules based on comment information in JavaScript files. You can use jsDoc tags such as command space, classes, methods, method parameters, etc. Thus developers can understand the meaning of the code, reduce maintenance costs, improve development efficiency.

Eslint-plugin-jsdoc configuration used

Configure the eslint-plugin-jsdoc plugin to regulate the writing of comments by developers in code for later maintenance.

  • Install the ESlint-plugin-jsdoc dependency
npm install --save-dev eslint-plugin-jsdoc
Copy the code
  • Eslintrc.* file information

Add the following code to the array of overrides in this file

{files: [' * * / IndicatorMangement/index in TSX '], / / want to use the rules file plugins: [' jsdoc ', 'header'], / / / / extends jsdoc plug-ins: [// 'plugin:jsdoc/recommended' //], rules: {// jsdoc/require-jsdoc': ['warn', {require: { ArrowFunctionExpression: true, ClassDeclaration: true, ClassExpression: true, FunctionExpression: true, MethodDefinition: true }, contexts: ['TSInterfaceDeclaration'] // Check whether the interface is aligned}], // Check whether the function is aligned with 'jsdoc/check-alignment': 'WARN ', // comment * aligned // 'jsdoc/check-examples': 'WARN ', // Write @example fun() in each function comment (how to use this function) // 'jsdoc/check-indentation': 'WARN ', // invalid padding 'jsdoc/check-param-names': [' WARN '], // check function parameter name and comment match 'jsdoc/check-syntax': 'WARN ', 'jsdoc/check-tag-names': 'warn', // check whether tag names are valid // 'jsdoc/check-types': 'WARN ', // report invalid type 'jsdoc/implements-on-classes':' WARN ', // // 'jsdoc/match-description': // 'jsdoc/newline-after-description': 'WARN ', // 'jsdoc/no-types': // 'jsdoc/no-undefined-types': 'warn', // 'jsdoc/require-description': ['warn', {descriptionStyle: 'any'}], // jsdoc/require-description-complete-sentence': ['warn'], // Descriptions must start with a capital case. // 'jsdoc/require-example': 'warn', // jsdoc/require-hyphen-before-param-description': 'jsdoc/require-param-description': 'jsdoc/require-param-description': 'jsdoc/require-param-description' 'jsdoc/require-param-name': 'warn', // jsdoc/require-param-name': 'warn', // 'Jsdoc' /require-returns': 'warn', // the parameter must be of type jsdoc 'jsdoc/require-returns': 'warn', 'WARN ', // Check if it is necessary to write return comment 'jsdoc/require-returns-description': 'jsdoc/require-returns-type': 'WARN ', // require return type' jsdoc/valid-types': 'warn', // valid type}}Copy the code

Or you can use the recommended configuration

File comments (eslint-plugin-header)

It is mainly for the annotation of the file head, which can detect whether the file head writes the annotation, and detect the specification of writing the annotation.

  • Install the ESlint-plugin-jsdoc dependency
npm install --save-dev eslint-plugin-header
Copy the code
  • Eslintrc.* file information

Add the following code to the array of overrides in this file

{files: [' * * / IndicatorMangement/index in TSX '], / / want to use the rules file plugins: [' jsdoc ', 'header'], / / / / extends jsdoc plug-ins: [// 'plugin:jsdoc/recommended' //], rules: {// jsdoc comment rules 'header/header': 1, 'block', [', {pattern: '@description: \\S', template:' * @description: '}, {pattern: ' @author: \\w', template: ' * @author: ' }, { pattern: ' @Date: \\S', template: ' * @Date: ' + moment(new Date()).format('YYYY-MM-DD HH:mm:ss') }, ' ' ] ] } }Copy the code

Install the plug-in koroFilerHeader

Add the following code to the setting customization area after VScode is installed

"fileheader.customMade": { "description": "", "author": "li.kexin", "Date": "Do not edit" / / file creation time (constant)}, "fileheader. CursorMode" : {" description ":" ", "param" : ""," returns ":" "},Copy the code

Generate file comment shortcut key: Ctrl+Alt+ I

/* * @description: Lilian * @date: 2021-04-16 16:25:40 */Copy the code

Generate function comment shortcut key: Ctrl+Alt+ T

/** * @description Function description * @param {number} a a parameter Description * @returns {*} Return value description */ const func = (a: number): number => { return a; };Copy the code

conclusion

At present, annotations are only detected by current function and file header annotations. Interface annotations are configured, but they cannot meet the requirements of the project. If there is a good method, please give more advice.