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

It's odd that MyLibrary.Controls.function1 is showing you anything at all, since MyLibrary.Controls doesn't have a function1. (The object that would be returned by new MyLibrary.Controls has a function1, but the function MyLibrary.Controls doesn't.) — T.J. Crowder
– T.J. Crowder, Commented Dec 21, 2022 at 14:06
Is there a particular reason this needs to be organized in this way? There are three things about it that are odd here in 2022 (IMHO): 1. It's using only ES5 features. ES2015 (actually ES2019/20 or so) is universally supported in non-obsolete environments, and for obsolete environments there are tools that can compile modern code to near-equivalent ES5. 2. It's creating instance functions rather than prototype functions, but the User and Control functions seem to be designed to be constructor functions. Sometimes you need to do that, but is that really the case? 3. It's not using modules. — T.J. Crowder
– T.J. Crowder, Commented Dec 21, 2022 at 14:09
The above is a genuine question, not snark. :-) It's just the simplest answer to your queston is: Write modern code, and the IDE will understand it. It's not an excuse for the IDE getting it wrong (and it clearly is, at least in my case with VS Code, in two ways -- showing function1 on MyLibrary.Controls when it doesn't have one, and showing the wrong docs -- as you said -- for new MyLibrary.Controls().function1. — T.J. Crowder
– T.J. Crowder, Commented Dec 21, 2022 at 14:10

T.J. Crowder · Accepted Answer · 2022-12-21 14:41:12Z

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:

Uses class syntax to create the constructor functions
Shares the methods across instances of classes by putting them on the prototype
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).

Collectives™ on Stack Overflow

JavaScript documentation issue when having functions with the same name

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related