JavaScript documentation issue when having functions with the same name

Question

I am working on a JavaScript library and trying to keep it well documented. I am structuring it in a way that I will end-up with functions for different objects, but the same name, and when adding documentation to it, it always picks up the signature for the first function and not the correct one for that object. I created a simple example for that:

`

var MyLibrary = MyLibrary || {};

MyLibrary = {
    User: function (T) {
        /**
         * This is my User.function1
         */
        this.function1 = function () {
            return "1";
        };
        /**
         * asdsa
         * @returns 
         */
        this.function2 = function () {
            return "2";
        };
    },
    Controls: function (T) {
        /**
       * This is my Controls.function1
       */
        this.function1 = function () {
            return "1";
        };
        /**
         * This is my Controls.function2
         */
        this.function2 = function () {
            return "2";
        };
    }
};

` When using the function MyLibrary.Controls.function1, the function name for MyLibrary.User.function1 is showing.

Am I missing something or is this because of the way I am structuring my code? any tips?

thanks

Answer 1

I don't know why VS Code gets those wrong, other than that it appears to be keying off just the function names.

In a comment you said you'd be open to solving the problem with a more modern structure, so here's what I'd probably do:

export class User {
    constructor(t) {
        // ...do something with `t`...
    }

    /**
     * This is my User.function1
     */
    function1() {
        return "1";
    }

    /**
     * asdsa
     * @returns
     */
    function2() {
        return "2";
    }
}

export class Controls {
    constructor(t) {
        // ...do something with `t`...
    }

    /**
     * This is my Controls.function1
     */
    function1() {
        return "1";
    }

    /**
     * This is my Controls.function2
     */
    function2() {
        return "2";
    }
}

That:

1. Uses class syntax to create the constructor functions
2. Shares the methods across instances of classes by putting them on the prototype
3. Exports the classes (constructor functions) via export

If you need to have private information that you previously were going to close over in the constructor, you might consider private fields which your constructor and methods can use, but which no other code can see.

Here's how you'd use those from another module:

import { Controls } from "./MyLibrary.js";

let controls = new Controls("arg");
console.log(controls.function1()); // <== Has the right documentation

Or if you like, you can do a module namespace import, which results in an object with properties for each named export:

import * as MyLibrary from "./MyLibrary.js";

let controls = new MyLibrary.Controls("arg");
console.log(controls.function1()); // <== Has the right documentation

More information can be found in the MDN links above, and in my recent(ish) book JavaScript: The New Toys which covers class syntax (Chapter 4), modern modules (Chapter 13), and private fields (Chapter 18).