background

Two weeks ago, I received a request to generate a document for our public interface library. The main reason is that the boss felt that such an important library did not even have a decent document. I searched the Internet for third-party tools that automatically identify JS and generate documentation, and finally chose JSDoc.

JSDoc function description

JSDoc is a tool that generates API documentation for javascript applications or libraries and modules based on comment information in javascript files. This article will not describe the specific use of JSDoc, mainly to explain how to add some configuration (JI) (LEI) based on the existing powerful functions of JSDoc, and take a look at the source code.

Take a look at what the JSDoc generated document looks like:

This is a document generated using JSDoc’s template tool Minama. You can see that it has the following functions:

  • Home front page, jsDoc supports displaying this page with a Markdown document
  • Class, Module, etc. Jsdoc uses the annotated block tag to identify which category the current component belongs to
  • Jsdoc will automatically parse the F in the Class (if annotated) and use the annotations to show some of the features of the method
  • Source, you can see the source in each method, which file it is in, how many lines it is in, click on it and you can see the corresponding code
  • .

New features

These are the main features of JSDoc, which are already very powerful. However, according to the requirements of business (boss), we have added the following features to JSDoc:

  • You can configure the name of the home page using the config.json file
  • Additional menus can be added under Home (jsDoc provides additional menus, but can only jump to other external links)
  • Markdown files can be parsed. By parsing, the markdown files are actually processed separately, because JsDoc can only handle JS files, especially if they are written in the source codeincludePattern: '.+\\.js(doc|x)? |md$'Of course, we have made some changes here
  • Parsed Markdown files are placed under the corresponding class or global document by name. Jsdoc’s classification has nothing to do with the path of the file, which results in the need to sort by document name
  • Generate an overview markdown that shows all the classes and methods in the document, with their description and href, to give the user an initial idea of the document
  • The new resource document store actually outputs some static resources to the document directory generated by JsDoc
  • Special comments are marked as nav, for example, only in a pair of commentsNo comment added“, the classification is marked red, used to remind developers which files need to add comments
  • .

JSDoc principle

Attached here is a working principle diagram of JSDOC that I drew before, without going into depth, just a simple analysis

As you can see, the flow chart is divided into two parts: left and right. Let’s take a look

  • The entry method in the upper left corner is to parse jSDoc’s configuration file, load the logging system, and begin file parsing
  • Then, through the entry file you configured, you perform a recursive walk through the file, creating the parsing method, parsing the file, generating the result, and eventually generating an AST
  • The generated result is then passed to the generateDocs method, which selects whom to hand the result to by determining if there is a template address in the configuration file
  • Here we use DocDash. In fact, most of our functionality additions and modifications are done in DocDash, which visually presents the results given by JSDoc.
  • Docdash exposes a publish method, which in turn generates the navigation bar on the left, the various parsed HTML and markdown files, and finally puts them in the output directory written in the configuration file

Source code analysis

node_modules/jsdoc/lib/jsdoc/config.js

Docdash publish.js to render the nav module. We can see that we use buildMemberNav to render the nav module, except global. Identified by the file name prefix GLobal_, place this section under the corresponding directory

So we did this one

  • Additional menus can be added under Home
  • You can configure the name of the home page using the config.json file
  • willGlobal_Prefix markdown files are placed in the global directory

This is the method that was added to the buildMemberNav method we saw above to generate an overview, generating a table of all the methods and descriptions for the result traversal. In other cases, the content of the comment is judged to identify uncommented files, and the file name is used to determine whether a markdown file with a filename prefix is the same as a class name. If so, the markdown file will be placed under the corresponding class, which will not be shown

  • Generate an overview of Markdown
  • Nav is identified for the special comment
  • Place markdown files with the same filename prefix and class name in the corresponding class directory

This is the node fs.writefilesync to output each class and MD file into HTML files, including the home page, overview, MD and each module

Jsdoc traverses and parses files. In the includePattern, we let go of md files. In this section, we need to process these files, otherwise JSDoc will parse md files as JS files.

Here we create a global variable to store the path of these MD files, and the final DOCDash to generate the HTML corresponding to these MD files

  • Markdown files can be parsed

The above are some functional additions to the JSDoc output. I hope this analysis will help you to generate a JS document.