Knowledge.ToString()

JSDoc Tokenizer Plugin to Replace the Token With Values From Config

If you are a JavaScript developer, you would have used the JSDoc to document your JavaScript code. I was trying to use the JSDoc for generating the documentation for my PramukhIME Javascript library. I have the core library and based on the plugin, I wanted to generate the documentation to show how the plugin works with the core library. This requires changing the example and description within the core library. It is not sustainable to manually make the change in the core library comments for each plugin. So in order to tackle this issue, I came up with this JSDoc plugin called “Tokenizer”. We define the tokens and it will be replaced with its values defined in the JSDoc Config values. This way, we can have different configuration per plugin and it will generate correct documentation for each plugin.

I am using JSDoc as a package for node.js and it is installed at C:\Users\USERNAME\AppData\Roaming\npm\node_modules\jsdoc. so I saved following code into the “tokenizer.js” file at “C:\Users\USERNAME\AppData\Roaming\npm\node_modules\jsdoc\plugins”

/**
    @overview Replaces the tokens [TOKEN_NAME] with its value defined in the jsdoc config.
    @module plugins/tokenizer
    @author Vishal Monpara
 */
'use strict';
 
var env = require('jsdoc/env');
 
var tokens = env.conf.tokenizer || {};
 
exports.handlers = {
    ///
    /// Replaces [TOKEN_NAME] with its value from config
    /// @param e
    /// @param e.filename
    /// @param e.source
    ///
    beforeParse: function(e) {
        var content = e.source;
        for(var token in tokens) {
            if(!tokens.hasOwnProperty(token)) {
                continue;
            }
            var regex = new RegExp('\\[' + token + '\\]','gi');
            content = content.replace(regex, tokens[token]);
        }
        e.source = content;
    }
};

Now I created custom JSDoc Config file at C:\Temp\jsdocconf.json which contains following code

{
    "tags": {
        "allowUnknownTags": true
    },
    "source": {
        "includePattern": ".+\\.js(doc|x)?$",
        "excludePattern": "(^|\\/|\\\\)_"
    },
    "plugins": ["plugins/tokenizer"],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false,
        "default": {
            "outputSourceFiles": false // set to false as it was true by default
        }
    },
    "tokenizer": {
        "KEYBOARD_NAME": "PramukhIndic",
        "KEYBOARD_JS_NAME": "pramukhindic.js",
        "LANGUAGE_NAME": "sanskrit"
        }
}

Now if my pramukhime.js file contains the text “Use the plugin [KEYBOARD_NAME]”, the documentation will contain “Use the plugin PramukhIndic”. I have used the following command to generate the file. “-c” uses custom config, “-d” outputs the file at that directory followed by Javascript file path

jsdoc --debug -c "C:\temp\jsdocconf.json" -d "C:\temp\doc" "C:\temp\pramukhime.js"

Share

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *