javascript - What are the practical and specific uses of JsDoc?

Question

Actual Phenomenon

1. To understand the role of JSDoc

For example, this file: https://github.com/showdownjs...

Expected Phenomenon

I thought of it myself:

1. Let the js interface become static (actually mainly 3)

2. Conveniently generate documents

3. Convenient for IDE, and also convenient for developers to call interfaces

So what are the practical benefits?

Answer 1

Whether you write JSDoc or not, the interface of JS is very dynamic. Functions can also use dynamic methods such as arguments and call to pass in various parameter formats, even if they do not match the parameter list of the receiver.

In terms of document generation, JSDoc can indeed achieve fast document generation. However, this has higher requirements on the organization mode of code modules, the length of comments and the level of developers, and automatically generated documents are usually not as readable as those directly maintained (for example, Yeoman, most of the automatically generated documents When dealing with inexplicable inheritance relationships).

In terms of improving the development experience, writing JSDoc can indeed improve the intelligence of the IDE in code prompts, and can also cooperate with eslint to discover potential problems during the development/compilation (packaging) phase.

In addition, when refactoring the code, a question often encountered is [when running here, what type should this variable be, and what value should it take in this state? 】Since both the front end and the back end are actually programming around data, if you use very dynamic data types and lack documentation, you will often find it difficult to understand when maintaining or refactoring the code [What does the function input and return? What], and JSDoc can effectively improve this.

However, I guess what the questioner really wants to ask is: [Since JSDoc has so many benefits, should I use this feature in my business code? 】

This question and [Should I write unit tests] are actually the same type of question. Everyone knows that writing unit tests and JSDoc has many benefits, but the problem is also very obvious: they will increase the amount of code and the length of the development cycle. Unlike unit test code in a separate test directory, JSDoc directly increases the length of business code (unless you use new Doc methods such as TypeScript spec). Therefore, in practice, for business codes that are not highly reusable, there is no problem at all without writing JSDoc or unit tests (the respondent has worked in several relatively small factories, and the actual business code of each front-end is to implement functions. For the first place, it would be nice if you don’t write noodle code. How can I have time to add long-winded documentation for you? Of course, for back-end positions that are basically based on table lookup and data return, it is easier to write Doc. respective specifications). When you reinvent the wheel and release some reusable code modules, complete JSDoc and unit testing are beneficial to the maintainability of the module, and can also make users feel that "the code quality is really good".

To put it simply, start JSDoc as soon as possible. The most important thing is to finish the business code early and not work overtime. Don’t ask for trouble.