CODEWITHSUNDEEP
javascripteslintjsdoc
Minh Nghĩa
Minh Nghĩa

Reputation: 1053

Should I use a compatible class with @param in JSDoc?

My Python API returns a JSON object, for example:

{
    a: 1,
    b: 'hi'
}

I also have a class for it in the client:

class Sth {
    constructor() {
        this.a = null;
        this.b = null;
    }
}

I receive an object and pass it without modification to a function. Should I use @param like this, instead of a simple @param {*}?

/**
 * @param {Sth} sth Is Sth appropriate here?
 */
function f(sth) {
    // Do sth
}

Upvotes: 1

Views: 107

Answers (2)

Adam Coster
Adam Coster

Reputation: 1462

Yes, that is appropriate. JSDocs will treat the class as a type. If the Sth class isn't available in the same file as your function you'll probably need a JSDoc type definition in that file, e.g. with /** @typedef {import("./path/to/your/class/file.js").Sth} Sth*/

If you can avoid @param {*} you generally should, since having more type information is always better!

Upvotes: 0

Graham P Heath
Graham P Heath

Reputation: 7389

Typically interaction with an outside/thirdparty resource is typed by an extern. If you're converting the code locally, that is: fetching and using the data to create an instance then your solution is correct: the class would be enough. If however you're fetching the data and the passing it to a constructor, you'll likely want to define a type in an externs.

When getting started with externs I find the closure debugger incredibly useful.

Upvotes: 1

Related Questions