JSDoc: node, events, listeners

722 views Asked by At

I am trying to document a pretty extensive (to me) code-base written in JS/NodeJS. JSDoc seems the only valid tool available but there are challenges. Here are two that I would like to know how to document:

1) I 'require' a module (Buzz) and then set a listener:

    var Buzz = require("Buzz");
    var ...
    .
    .
    .

    ["in_call", "idle", "offline", "busy"].forEach(function (e) {
        Buzz.on("state:" + e, sounds.stop);
    });

    Buzz.on("message", function (message) {
        if (message && !message.read)
            sounds.play("message");
    });

2) When using 'Vue.js', it now requires the use of functions to set properties, meaning there are functions as properties within the function. Below is a kludgy way I make jsdoc document the functions, but clearly it makes no sense as there really isn't a ae-admin 'class'.

    /**
     * @class  ae-admin
     */

    module.exports = Vue.component("ae-admin", {
        className: "ae-admin",
        template: template,
        /**
         * [data description]
         * @memberOf ae-admin
         * @return {[type]} [description]
         */
        data: function () {
            return {
            .
            .
            .
            };
        },
        /**
         * ready description]
         * @memberOf ae-admin
         * @return {[type]} [description]
         */
        ready: function () {},
        methods: {
            /**
             * [set_page description]
             * @memberOf ae-admin
             * @param {[type]} page [description]
             */
            set_page: function (page) {
                this.$data.page = page;
            },
            .
            .
            .

It is interesting that JSdoc really seems to be a javadoc lookalike with js paradigms being an afterthought. Anyways, any help would be appreciated.

1

There are 1 answers

0
Etai On

With modules, there's the @exports and @module tags.

These will work much better for documenting your code than @class.

You can see some really great examples from usejsoc, here as well as their module and exports definitions.

I use AMD module syntax, so I can't comment on the exact format for you, but I'm sure you should find some examples there.

If you still choose to use classes, try using /** @lends className **/ right before your registered component instead of the class, i.e.

module.exports = Vue.component("ae-admin", /** @lends ae-admin **/{

Or even @lends ae-admin.prototype.