documentationjs / documentationjs/documentation
Support standard class constructor JSDoc
- 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
Assessment
This issue has not been assessed yet.