How to document a class in JSDoc 3, or Help! My JSDocs aren’t including my classes!

JSDoc 3 is opaque about how it chooses to document classes. This isn’t exactly surprising, since I would throw up my hands at the myriad number of ways a class can be declared in JavaScript. Here’s how you get a class to be autodocumented.

JSDoc automatically documents classes that are in the global namespace:

1
2
3
4
5
6
7
8
9
10
11
12
/**
* @classdesc This class will be documented automatically because it is not in
* another function.
* @constructor
*/
function TestClassGlobal() {
/**
* This is a public method and will be documented automatically.
*/
this.publicMethod = function() {
};
}
/**
* @classdesc This class will be documented automatically because it is not in
* another function.
* @constructor
*/
function TestClassGlobal() {
/**
* This is a public method and will be documented automatically.
*/
this.publicMethod = function() {
};
}

However, if you’ve been enclosing your classes in functions like a good programmer, JSDoc won’t include those anywhere:

1
2
3
4
5
6
7
8
9
10
define([], function() {
/**
* @classdesc This won't be automatically documented,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}
});
define([], function() {
/**
* @classdesc This won't be automatically documented,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}
});

There are two ways around this – you can explicitly add @global, or use @memberof to make the class belong to a namespace:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
define([], function() {
/**
* @classdesc This won't be automatically documented unless you add memberof,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}
 
/**
* @classdesc This won't be automatically documented unless you add global,
* because it's inside another function.
* @constructor
* @global
*/
function TestClassForcedGlobal() {
}
});
define([], function() {
/**
* @classdesc This won't be automatically documented unless you add memberof,
* because it's inside another function.
* @constructor
* @memberof Namespace
*/
function TestClassNamespace() {
}

/**
* @classdesc This won't be automatically documented unless you add global,
* because it's inside another function.
* @constructor
* @global
*/
function TestClassForcedGlobal() {
}
});

1 comment

Leave a Reply

Your email address will not be published. Required fields are marked *