JSDoc + Mongoose : how to document Mongoose models?

Question

I have Mongoose schema and a model:

var MyClientSchema = new mongoose.Schema({
    fist_name: {
        type: String
    },
    phone_number: {
        type: String
    }
});

var MyClient = mongoose.model('MyClient', MyClientSchema);

How should I document (using JSDoc) MyClient and/or MyClientSchema to get tab-completion and type suggestions from WebStorm for both methods inherited from mongoose.model like remove, findOne, find - and inherited from schema - like phone_number and first_name ?

Vasyl Boroviak · Answer 1 · 2018-07-12T04:11:18.517

I found @class (or its synonym @constructor) works for schema properties:

/**
 * @class MyClient
 */
var MyClientSchema = new mongoose.Schema({
    fist_name: {
        type: String
    },
    phone_number: {
        type: String
    }
});

var MyClient = mongoose.model('MyClient', MyClientSchema);

The @alias works for methods declared the old way:

/**
 * @alias MyClient.prototype.getDescription
 */
MyClientSchema.method('getDescription', function () {
    return this.first_name + " " + this.phone_number;
});

However, you can mark all methods as part of MyClient at once if you use the new way of declaring methods:

/**
 * @class MyClient
 * @mixes {MyClientSchema.methods}
 */
var MyClientSchema = new mongoose.Schema({ ...

/** @mixin */
MyClientSchema.methods;

MyClientSchema.methods.getDescription = function () {
    return this.first_name + " " + this.phone_number;
};

All the above tested in latest WebStorm version (2018.2). It works.

Things which do not work:

Mongoose built-in methods like .find() or .save()
The .methods syntax highlight works but code completion doesn't.

Updates are welcome!

Did this work for you in second file that imported MyClient. Was there any additional tags needed for this to work? — jeffheifetz, Apr 17 '19 at 15:06

Kalana Demel · Answer 2 · 2017-04-28T02:23:48.330

2

Although it might not fit your specific requirement, this jet brains tutorial in the official documentation explains most of what you need

https://www.jetbrains.com/help/webstorm/2017.1/creating-jsdoc-comments.html

for example,

/**
 * MyClientSchema schema
 * @constructor MyClient
 */

var MyClientSchema = new mongoose.Schema({
        fist_name: {
            type: String
        },
        phone_number: {
            type: String
        }
    });

and the following js might be a guide foe you to do almost everything you need

http://nagyv.github.io/estisia-wall/models.js.html

edited Apr 28 '17 at 02:23

answered Apr 27 '17 at 14:41

Kalana Demel

3,220
3
21
34

Great reply. How are you handling validators used by the model? – SomeDutchGuy Oct 10 '19 at 08:00

score 1 · Answer 3 · answered Apr 29 '23 at 10:02

For me it worked as simple as:

var MyClientSchema = new mongoose.Schema({
    fist_name: {
        type: String
    },
    phone_number: {
        type: String
    }
});

var MyClient = mongoose.model('MyClient', MyClientSchema);

/**
 * @typedef {typeof MyClient} MyClientModel
 * @typedef {typeof MyClient.schema.obj} Client
 */

/**
 * @param {Client} client A MyClient document
 */
function (client) {
    client.[<here you get a suggestion for first_name>]
}

With the important note that you will not get phone_number and first_name from the schema's type but from the type of MyClient.schema.obj which defines a document.

JSDoc + Mongoose : how to document Mongoose models?

3 Answers3

Linked