documentationjs / documentationjs/documentation

Support standard class constructor JSDoc

Open
#1,091 3 comments 8 reactions 0 assignees View on GitHub
Dominant language
JavaScript
Stars
5.8k
Forks
481
PR merge metrics
No merged PRs in 30d

Description

The way that documentation.js forces us to document classes is incorrect:

```js
/**
* A foo.
* @param {*} value Value.
*/
class Foo {
constructor(value) {
this.value = value
}
}
```

[Here is the standard way](http://usejsdoc.org/howto-es2015-classes.html#documenting-a-simple-class):

```js
/**
* A foo.
*/
class Foo {
/**
* Constructs a new foo.
* @param {*} value Value.
*/
constructor(value) {
this.value = value
}
}
```

Attempting to use the standard approach will result in documentation not appearing, or the constructor docs take over the class description.

Not only is the documentation.js way unintuitive and a common gotcha, but it causes problems using JSDoc linters that expect a standard approach. This ESLint config will report an error that the constructor is missing JSDoc:

```json
{
"rules": {
"require-jsdoc": ["error", {
"require": {
"ClassDeclaration": true,
"MethodDefinition": true
}
}]
}
}
```

There is no way to configure the ESLint `require-jsdoc` to ignore `constructor`. You can't use normal eslint ignore rule directive comments (`// eslint-disable-next-line require-jsdoc`) as a workaround due to https://github.com/documentationjs/documentation/issues/1090. You're just stuck 😔

As part of a fix:

- Remove [this warning](https://github.com/documentationjs/documentation/blob/v8.0.0/src/parsers/javascript.js#L108).
- Remove [this advice](https://github.com/documentationjs/documentation/blob/v8.0.0/docs/RECIPES.md#classes).

Related:

- https://github.com/documentationjs/documentation/issues/109

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.