Analyze how to automatically generate Vue component documentation

1. Current situation

The Vue framework is widely used in front-end development. When a Vue project developed by multiple people is maintained for a long time, many common components will often be precipitated. At this time, it often happens that one person develops a component while other maintainers or newcomers do not know what the component does or how to use it. They have to look through the source code again, or they don't even notice the existence of the component, resulting in duplicate development. At this time, it is very necessary to maintain the corresponding component documents to ensure a good collaboration between different developers.

However, traditional manual maintenance of documents will bring new problems:

• The efficiency is low. Writing documents is a time-consuming and laborious physical task. After finally finding the time to develop the component, you still have to write the documents. Just thinking about it makes me feel overwhelmed.
• Error-prone, the document content is prone to errors and may not be consistent with the actual component content.
• It is not smart. When updating components, you need to manually synchronize the changes to the document, which is time-consuming and prone to omissions.

The ideal way to maintain documents is:

• The workload is small, and it can be combined with Vue components to automatically obtain relevant information, reducing the workload of writing documents from scratch.
• The information is accurate, and the key information of the component is consistent with the component content without any errors.
• Intelligent synchronization: when Vue components are iteratively upgraded, the document content can be automatically updated synchronously without the need to manually verify whether the information is consistent.

2. Community Solutions

2.1 Business review

In order to achieve the above ideal effect, I searched and studied the solutions in the community. Currently, Vue officially provides Vue-press, which can be used to quickly build Vue project documents, and there is also a library that can automatically extract information from Vue components.

However, the existing third-party libraries cannot fully meet the needs. There are mainly two problems:

• The information is not comprehensive, and some important content cannot be obtained, such as the inability to process v-model, the inability to parse the attribute modifier sync, and the inability to obtain detailed information on the function input parameters in methods.
• For example, in the following example, the value attribute and the input event can be combined to form a v-model attribute, but this information is not reflected in the generated document, and the reader of the document must understand and judge it for himself. And the generated documentation does not show whether sync is supported.

There are many custom logos, and the naming of the logos is too personalized, which causes great intrusion into the original code. For example, in the code in the figure below, in order to mark comments, it is necessary to add additional identifiers such as "@vuese" and "@arg" to the original business code, which adds some business-irrelevant content to the business code.

3. Technical Solution

In response to the problems mentioned above and the shortcomings of the community solutions, our team has developed a small tool specifically for Vue component information acquisition and component document output. The general effect is as follows:

In the above picture, on the left is a common Vue single-file component, and on the right is the generated document. We can see that we have successfully extracted the following information from the component:

• The name of the component.
• Description of the component.
• props, slots, events, methods, etc.
• The annotation content of the component.

Next we will explain in detail how to extract this information from the component.

3.1. Vue file parsing

Since we want to extract information from Vue components, the first question is how to parse Vue components. Vue officially developed the Vue-template-compiler library specifically for Vue parsing, and we can also use the same approach here. By consulting the documentation, we can see that Vue-template-compiler provides a parseComponent method to process the original Vue file.

import { parseComponent } from 'Vue-template-compiler'
const result = parseComponent(VueFileContent, [options])

The processed results are as follows, where template and script correspond to the text contents of template and script in the Vue file respectively.

export interface SFCDescriptor {
  template: SFCBlock | undefined;
  script: SFCBlock | undefined;
  styles: SFCBlock[];
  customBlocks: SFCBlock[];
}

Of course, it is not enough to just get the text, the text needs to be further processed to obtain more information. After getting the script, we can use babel to compile js into js AST (abstract syntax tree). This AST is a common js object that can be traversed and read through js. With Ast, we can get the detailed component information we want.

import { parse } from '@babel/parser';
const jsAst = parse(script, [options]);

Next, let's look at template. Continuing to search the documentation of Vue-template-compiler, we find the compile method. Compile is specifically used to compile template into AST, which just meets the needs.

import { compile } from 'Vue-template-compiler'
const templateAst = compile(template, [options]);

The ast in the result is the compilation result of template.

export interface CompiledResult {
  ast: ASTElement,
  render: string,
  staticRenderFns: Array<string>,
  errors: Array<string>
}

Through the first step of file parsing, we successfully obtained the Vue template ast and the AST of js in the script. In the next step, we can get the information we want from them.

3.2 Information Extraction

Depending on whether an agreement is required, information can be divided into two types:

• One is that it can be obtained directly from the Vue component, such as props, events, etc.
• The other type requires additional agreed formats, such as component description comments, props property descriptions, etc. This part can be put in the comments and obtained by parsing the comments.

In order to conveniently read information from ast, here is a brief introduction to a tool @babel/traverse, which is an official library provided by babel specifically for traversing js AST. How to use:

import traverse from '@babel/traverse'

traverse(jsAst, options);

By configuring the callback function of the corresponding content in options, you can get the desired ast node. For specific usage, please refer to the official documentation

3.2.1. Directly accessible information

The information that can be directly obtained from the code can effectively solve the problem of information synchronization. No matter how the code changes, the key information of the document can be automatically synchronized, eliminating the trouble of manual proofreading.

The information that can be directly obtained is:

• Component props
• Provide methods for external calls
• Events
• slots

Both 1 and 2 can use traverse to directly traverse the object nodes named props and methods on the js AST to obtain them.

It is a little bit more troublesome to obtain the event. You can locate the event by looking for the $emit function. The $emit function can listen to MemberExpress (complex type node) in traverse, and then determine whether it is an event by whether the attribute name on the node is '$emit'. If it is an event, then read the arguments field in the $emit parent. The first element of arguments is the event name, and the following elements are the event parameters.

this.$emit('event', arg);

traverse(jsAst, {
 MemberExpression(Node) {
  // Determine if it is an event
  if (Node.node.property.name === '$emit') {
  // The first element is the event name const eventName = Node.parent.arguments[0];
  }
 }
});

After successfully obtaining Events, combining Events and props, we can further determine the two special properties in props:

• Whether v-model exists: Check whether there is a value attribute in props and whether there is an input event in Events to determine.
• Whether a property of props supports sync: Determine whether there is an event starting with update in the time name of Events, and whether the event name is the same as the property name.

The information of slots is stored in the AST of the template above. Recursively traverse the template AST to find the node named slots, and then find the name on the node.

3.2.2 Information that needs to be agreed upon

Why do we need to agree on additional content besides the component information that can be obtained directly? First, the information that can be directly obtained is relatively thin and is not enough to support a relatively complete component document. Second, we write a lot of comments when developing components in our daily life. If we can directly extract some comments and put them into the document, the workload of document maintenance can be greatly reduced.

The following are some of the things that can be agreed upon:

• The name of the component.
• An overview of the component.
• Text description of props, events, methods, and slots.
• Detailed description of Methods tags and input parameters. All of these contents can be maintained in comments. The reason for maintaining them in comments is that comments can be easily obtained from the js AST and template AST mentioned above. When we parse the Vue component information, we can parse this part of the targeted instructions together.

Next, we will focus on how to extract annotations and how to match the annotations with the annotated content.

Comments in js can be divided into leadingComments and trailingComments according to their positions. Comments in different positions will be stored in corresponding fields. The code is shown as follows:

//Header comment export default {} //Tailer comment

Parsing results

const exportNode = {
  type: "ExportDefaultDeclaration",
  leadingComments: [{
    type: 'CommentLine',
    value: 'Header comment'
  }],
  trailingComments: [{
    type: 'CommentLine',
    value: 'Tail comment'
  }]
}

At the same position, comments can be divided into single-line comments (CommentLine) and block-level comments (CommentBlock) according to their different formats. The difference between the two types of comments is reflected in the type field of the comment node:

/** * Block level comments */ // Single line comment export default {}

Parsing results

const exportNode = {
  type: "ExportDefaultDeclaration",
  leadingComments: [
    {
      type: 'CommentBlock',
      value: 'Block-level comment'
    },
    {
      type: 'CommentLine',
      value: 'Single-line comment'
    }
  ]
}

In addition, from the above parsing results we can also see that the comment node is mounted in the commented export node, which also solves another problem we mentioned above: how to obtain the association between the comment and the commented node - in fact, Babel has done it for us when compiling the code.

The template searches for comments and the commented content differently. The comment node in the template exists as a DOM node like other nodes. When traversing the node, we determine whether it is a comment node by judging whether the value of the isComment field is true. The commented content is located after the sibling node:

<!--template's comment--> <slot>the commented node</slot>

Parsing results

const templateAst = [
  {
    isComment: true,
    text: "template comments",
    type: 3
  },
  {
    tag: "slot",
    type: 1
  }
]

Now that we know how to process comments, we can do more with them. For example, you can use a @public tag in the comments of methods to distinguish between private and public methods. If you want more details, you can also refer to the format of js-doc, another library specifically used to parse js comments, to further explain the method input parameters and enrich the content of the document.

We only need to cut and read the text after obtaining the annotation content, for example:

export default {
  methods: {
    /**
     * @public
     * @param {boolean} value parameter description*/
    show(value) {}
  }
}

Of course, in order to avoid intrusion into the code too much, we still need to add as few additional identifiers as possible. The parameter description uses the same format as js-doc, mainly because this solution is more commonly used and code editors automatically support easy editing.

IV. Conclusion

Writing component documentation is a great way to improve collaboration among front-end development members within a project. A well-maintained document will greatly improve the development experience. And if we can further use tools to automate the process of maintaining documents, the happiness of development can be further improved.

After a series of explorations and attempts, we successfully found a solution for automatically extracting Vue component information, which greatly reduced the workload of maintaining Vue component documents and improved the accuracy of document information. In terms of specific implementation, we first use vue-template-compiler to process the Vue file to obtain the template AST and js AST. With these two ASTs, we can get more detailed information. Let's sort out the content and acquisition methods that can be obtained in the documents we have generated so far:

As for whether to output the content in Markdown or json format after obtaining it, it depends on the actual development situation.

V. Outlook

What we are discussing here is to obtain information and output directly from a single Vue file, but like many third-party component libraries such as elementUI's documentation, there is not only component information but also display examples. If a component library is relatively well maintained, a component should have a corresponding test case. So is it possible to extract the component's test case as well and realize automatic extraction of the example part in the component file? This is also an issue worth studying.

The above is the detailed content of analyzing how to automatically generate vue component documents. For more information about automatically generating vue component documents, please pay attention to other related articles on 123WORDPRESS.COM!