Introduction to the

Buried statistical problem is always a very important part of business. Buried data is an important basis for business analysis and technical optimization.

With the increasing number of business iterations and personnel changes, there are more and more historical baggage. PM often comes to the development students to ask what is the buried point of certain function. On the one hand, the communication cost is high, on the other hand, the frequent interruption to the development students also seriously affects the development efficiency.

To solve these problems, we developed a set of automatic collection, classification, reporting and display system for scattered buried points in the project to assist relevant business parties to view and analyze business data.

The main process is divided into three parts: routing arrangement (dependency analysis), buried point extraction and reporting, and display platform.

This time mainly introduces the extraction and reporting of buried sites.

Point marked

First of all, it is pointed out that buried points in our business are mostly manual buried points, such as:

this.$log('page_view', pageType, backup);
Copy the code

Distributed across pages and components.

One of the primary maintenance issues is that in many cases, after a long time, even the developers themselves have trouble remembering the meaning of the buried point and the meaning of the attached parameters.

It’s easy to think of a way to improve maintainability by adding annotations to solve this problem. But how?

Here we turn to JSDoc, the general annotation specification, to illustrate our burying point.

It is also marked as a buried point by a custom tag.

Like this:

$this.$log('page_view', pageType, backup);Copy the code

After that, we began to prepare for the collection.

Buried point processing

pretreatment

So our collection is also done based on JSDoc. But before we start, we need to process our source files. Like most of our projects, Babel needs to be converted, because some advanced syntax is also not supported by JSDoc and will be interrupted by syntax errors during processing.

Vue-template-compiler is also used to extract JS code from VUE.

And conversion to TypeScript.

Please refer to the official documentation for JSDoc plug-in writing

Handlers = {beforeParse: function(e) {// Preprocess files}}Copy the code

tag

The next step is to customize our tag @log

Dictionary.definetags = function (dictionary) {// define @log tag dictionary.defineTag('log', {// declare that custom tags can contain text like: Name '@param {string} name-description' canHaveName: true, onTagged: Function (doclet, tag) {doclet.meta.log = {name: tag.text}; }}); // define the @backup tag dictionary.definetag ('backup', {onTagged: Function (doclet tag) {/ / described several backup stored doclet. Backup = doclet. Backup | | []; if (tag.value || tag.text) { doclet.backup.push(tag.value || tag.text); }}}); }Copy the code

Note that in addition to the @log tag, there is another @backup tag, which is used to collect buried points.

In this way we mark our buried points with JSDoc custom tags. The next step is how to integrate buried points into a format we can understand.

parsing

If you haven’t noticed, the block comment added is actually for method definitions, but we’re using it for method calls, and the result is that the JSDoc tool ignores this type of comment.

Fortunately, JSDoc has a corresponding tag: @name.

The @name declaration is added to the comment to indicate what the comment means so that JSDoc can collect it.

And then you need to mark actionType,pageType, which you can do with the @param tag that you already have.

@param {string} pageType - pageType description @param {string} actionType - actionType description * @backup {string} backup - */Copy the code

The key is how to parse actionType and pageType in buried methods.

The common cases we encounter with buried method calls are:

// An object argument log_method({actionType: ", pageType: ", backup: {}}); // an object argument, a string argument log_method({actionType: ''}, 'pageType'); // Two object arguments log_method({actionType: ''}, {}); // a string argument log_method('action_type'); // Two string arguments log_method('action_type', 'page_type'); / / three parameters log_method (' action_type ', 'page_type, {}); // Two arguments log_method('action_type', {foo: 'bar'}); // Three arguments log_method('action_type', null, {}); // three arguments log_method('action_type', void 0, {});Copy the code

As you can see, there are many invocation forms, and these use ways are already present in the project, so they should be compatible.

How can we extract and parse the parameters accurately in so many cases? Again, JSDoc provides the entry point: astNodeVisitor.

exports.astNodeVisitor = {
    visitNode: function(node, e, parser, currentSourceName) {
        // do all sorts of crazy things here
    }
};
Copy the code

Here we use AST, before we big zhuanzhuanfe (zhuanzhuanfe) public number article has introduced, here will not expand to talk about, generally speaking, is through AST to get actionType,pageType and the resolution of the parameter backup.

At this point, the parsing problem is basically solved, followed by processing the data.

collect

By default, comments collected by JSDoc are output as HTML files according to the built-in templates, but we don’t really need a file preview here, just the data, and we have our own data presentation platform for the future.

So, data processing is done by customizing JSDoc templates:

JSDoc template:

/** * Generate documentation output. * * @param {TAFFY} data - A TaffyDB collection representing * all the symbols documented in your code. * @param {object} opts - An object with options information. * @param {Tutorial} tutorials */ Export.publish = function(taffyData, opts, tutorials) {// the data we need is in taffyData}Copy the code

All the data we need is in taffyData.

In the template we need to do the following things according to our needs:

  • Provide custom methods for content that does not vary much, such as PageType
  • Output buried points in the given file order (routing)
  • Provides markdown file output for local preview
  • Repeat points buried
  • Report to the buried site display platform

Summary process:

configuration

The above is the key step of buried point collection. Considering the differences of buried point reporting methods of different projects, we provide configuration files to define buried point method name, custom pageType method, custom actionType method, public backup definition, project information and so on. Please refer to the usage documentation for details.

conclusion

With the help of the JSDoc plug-in, we have completed the extraction of data from annotations to buried points, which requires an understanding of the corresponding methods of JSDoc and the decomposition of our own requirement function points.

This is also a practical use scenario for AST and JS annotations, which I hope will inspire you.

references:

  1. JSDoc plugin jsdoc.app/about-plugi…
  2. ast explorer astexplorer.net/