Method of Vue component document generation tool library

The two things programmers hate the most are writing documentation and others not writing documentation. Is there any way to generate documents directly based on Vue components? Of course there are. However, third-party applications may not be able to be used in conjunction with existing projects, and often require additional annotations to mark the extracted information. Some common problems when using third parties

• The document extraction information is not comprehensive. There may be some information you need to extract but it is not supported. In this case, you can only modify the third-party plug-in source code.
• Additional annotation information is required to mark the method. For example, vuese needs to mark the method with @vuese, @arg, etc. to provide method information.

As the saying goes, DIY brings prosperity. Create your own vue document generation tool and use it in conjunction with your own project. A component document generally needs to provide component name and description (name), component properties (props), component methods (methods), component events (event), slots (slot), and comments on these parts to generate description information. Next, we will implement the extraction of several parts step by step.

Parsing .vue files

Generally, a .vue file is divided into three parts: template, script, and style. We don't need the content of the style part, so we need to extract the template and script contents separately. Vue officially developed the Vue-template-compiler library specifically for Vue parsing. We can use it directly to parse and extract .vue files. Vue-template-compiler provides a parseComponent method to process the original Vue file.

const compiler = require('vue-template-compiler')
const result = compiler.parseComponent(vueStr, [options])

// parseComponent returns template, script, style content,
export interface SFCDescriptor {
  template: SFCBlock | undefined;
  script: SFCBlock | undefined;
  styles: SFCBlock[];
  customBlocks: SFCBlock[];
}

After getting the text of each part, you also need to convert it into ast (abstract syntax tree). The template part can directly use the compile method provided by Vue-template-compiler to generate ast. The script part needs to use other methods to generate ast. Here, the babel module is used to process the js text.

const compiler = require('vue-template-compiler')
//vueStr .vue file content const vue = compiler.parseComponent(vueStr)

//Generate AST for HTML part 
let template = compiler.compile(vue.template.content, {
    preserveWhitespace: false,
    comments: true // Generate comment information})

Use @babel/parser (Babel parser, the JavaScript parser used in Babel) to process js text content.

const parse = require('@babel/parser');

//Generate ast for js part
let jsAst = parse.parse(vue.script.content, {
    allowImportExportEverywhere: true 
})

Extract document information

Through the file parsing work in the previous step, we have successfully obtained the Vue template ast and the js ast in the script. The next step is to get the information we want from them. Here you need to use the @babel/traverse tool, which is a node tool for traversing js ast. You can view the generated content of ast here, which is convenient for viewing various node information.

const traverse = require('@babel/traverse');
traverse.default(jsAst, {
  enter(path){ // start},
  //Support custom nodes, for example, when the node type is ExportDefaultDeclaration, drop this method ExportDefaultDeclaration(){

  }
})

Extract component name, description, props, methods, model

The corresponding node type generated by export default is ExportDefaultDeclaration. The declaration attribute is the options of the corresponding component. By traversing the declaration attributes, you can get node information such as name, props, methods, model, etc.

Example

let componentInfo = {}
traverse.default(jsAst, {
  ExportDefaultDeclaration(path){
    path.node.declaration.properties.forEach(item => {
        switch (item.key.name) {
            case 'props':
                componentInfo.props = extractProps(item) // Extract props
                break;
            case 'methods':
                componentInfo.methods = extractMethods(item) // Extract methods
                break
            case 'name':
                componentInfo.name = item.value.value // Get the component name break
            case 'model':
                componentInfo.model = extractModel(item) // Extract model
                break
            default:
                break;
        }
    });
  }
})

Extract description

Comments in js are divided into single-line and multi-line types. Generating ast will also generate different types. See the example below.

/** 
 *Multi-line notes* Used to upload document information*/
// Single-line comment export default {
}
// End comment

You can see that there are two types of nodes: CommentBlock and CommentLine. The head comments are placed in leadingComments, and the bottom comments are in trailingComments.

Generally, the component description comment is placed on the export default, and the comment information is simply extracted.

// ExportDefaultDeclaration insert the following code if (path.node.leadingComments) {
    componentInfo.desc = path.node.leadingComments.map(item => {
        if (item.type === 'CommentLine') {
            return item.value.trim()
        } else {
            return item.value.split('\n').map(item => item.replace(/[\s\*]/g, '')).filter(Boolean)
        }
    }).toString()
}

Extraction methods

Because the comments in methods need additional description of output parameters, input parameters and other information that require additional processing, the jsdoc comment standard is still relatively popular. Here, you can define the extraction rules according to your needs, and you also need to extract async to identify whether it is an asynchronous function.

/**
 * Method description * @param {Bool} type parameter description * @returns return value description */

Extracting props

The extraction of props needs to distinguish the following situations. It is still a bit troublesome to extract default and validator. Validator verification can be extracted through simple description of comments, but default is not easy to handle.

{
    propA: Number, // only type propB: [String, Number], // only type but supports multiple propC: { 
      type: String,
      required: true
    },
    propD: {
      type: Number,
      default: 100 // with default value},
    propE: {
      type: Object,
      default () { // The default value requires the function to return return { message: 'hello' }
      }
    },
    propF: {
      default: function () { // The default value requires the function to return a different ast node type than the default above return { message: 'hello' }
      }
      validator: function (value) { // check return ['success', 'warning', 'danger'].indexOf(value) !== -1
      }
    }
}

Here I use @babel/generator to convert the default code, and convert it into a function call through eval to return the default value. types is the @babel/types module, which is used to determine the node type.

// Get the default value of Props function getDefaultVal (node) {
    if (types.isRegExpLiteral(node) || types.isBooleanLiteral(node) || types.isNumericLiteral(node) || types.isStringLiteral(node)) {
        return node.value
    } else if (types.isFunctionExpression(node) || types.isArrowFunctionExpression(node) || types.isObjectMethod(node)) {
        try {
            let code = generate.default(types.isObjectMethod(node) ? node.body : node).code
            let fun = eval(**0,${types.isObjectMethod(node) ? 'function ()' : ''} $[code]**)
            return JSON.stringify(fun())
        } catch (error) {
        }
    }
}

Extract model

This is relatively simple, you can just get it directly.

Extracting Component Events

The event of a component cannot be directly obtained from the corresponding node. The event position can only be located through the $emit method. In traverse, MemberExpress (complex type node) can be used, and then whether it is an event can be determined by whether the attribute name on the node is $emit.

You can see that the event name is in arguments on the MemberExpress parent, and the comments are in the one level above.

const extractEvents = (path) => {
    // The first element is the event name const eventName = path.parent.arguments[0]; 
    let comments = path.parentPath.parent.leadingComments
    return {
        name: eventName.value,
        desc: comments ? comments.map(item => item.value.trim()).toString() : '——'
    }
}

MemberExpression (path) {
    // Determine if it is an event
    if (path.node.property.name === '$emit') {
        let event = extractEvents(path)
        !componentInfo.events && (componentInfo.events = {});
        if (componentInfo.events[event.name]) {
            componentInfo.events[event.name].desc = event.desc ? event.desc : componentInfo.events[event.name].desc
        } else {
            componentInfo.events[event.name] = event
        }
    }
}

After successfully obtaining Events, you can further determine whether the attribute supports .sync and v-model by combining Events, Props, and Model.

Extract component slots

First, you need to write a function to traverse the ast of the Vue template. Vue-template-compiler does not provide a function similar to @babel/traverse for traversing ast.

Simple implementation of a traversal template abstract tree function

const traverserTemplateAst = (ast, visitor = {}) => {
    function traverseArray (array, parent) {
        array.forEach(child => {
            traverseNode(child, parent);
        });
    }

    function traverseNode (node, parent) {
        visitor.enter && visitor.enter(node, parent);
        visitor[node.tag] && visitor[node.tag](node, parent);
        node.children && traverseArray(node.children, node);
        visitor.exit && visitor.exit(node, parent);
    }

    traverseNode(ast, null);
}

The structure of the Vue template's ast is relatively clear. It does not have as many types as the js ast. You only need to distinguish different tags. Comments are separated into separate nodes, so when searching for a slot node, you also need to find its previous adjacent node to determine whether it is a comment.

traverserTemplateAst(template.ast, {
    slot (node, parent) {
        !componentInfo.slots && (componentInfo.slots = {})
        // Get the node position let index = parent.children.findIndex(item => item === node)
        let desc = 'No description', name = '-';
        if (index > 0) {
            let tag = parent.children[index - 1]
            // isComment determines whether it is a comment if (tag.isComment) {
                desc = tag.text.trim()
            }
        }
        if (node.slotName) name = node.attrsMap.name
        componentInfo.slots[name] = {
            name,
            desc
        }
    }
})

Conclusion

So far, we have simply realized the automatic generation of Vue component information. Of course, there are still several situations that have not been considered, such as the event $emit in the template and the slot in the render function. However, the implementation of extracting this part is similar. You can view the source code of this article here.

This is the end of this article about the methods of the Vue component document generation tool library. For more relevant Vue component document generation tool content, please search for previous articles on 123WORDPRESS.COM or continue to browse the following related articles. I hope everyone will support 123WORDPRESS.COM in the future!