documentationjs / documentationjs/documentation
Property/method distinction and @type support.
- Dominant language
- JavaScript
- Stars
- 5.8k
- Forks
- 481
- PR merge metrics
- No merged PRs in 30d
Description
**If you're reporting a bug, please include _input code_, _output documentation_,
a description of what you expected to happen, and what happened instead.**
Input
```
documentation build foo.js --format md --sort-order alpha
```
```js
/**
* Represents a foo, provides access to the bar and the zab.
*/
function Foo () {
/**
* It is the foo.
* @type {number}
*/
this.foo = 1;
Object.defineProperties(this, /** @lends Foo */ {
/** @type {number} It is the bar. */
bar: {
get: function() {
return 2;
}
},
/** @type {number} It is the zab. */
zab: {
get: function() {
return 3;
}
}
});
}
Object.assign(Foo.prototype, /** @lends Foo */ {
/**
* Gets the foo.
* @return {number}
*/
getFoo: function () {
return this.foo;
},
/**
* Gets the bar.
* @return {number}
*/
getBar: function () {
return this.bar;
}
});
```
Output
```markdown
### Table of Contents
- [Foo](#foo)
- [foo](#foo-1)
- [bar](#bar)
- [getBar](#getbar)
- [getFoo](#getfoo)
- [zab](#zab)
## Foo
Represents a foo, provides access to the bar and the zab.
### foo
It is the foo.
### bar
### getBar
Gets the bar.
Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**
### getFoo
Gets the foo.
Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)**
### zab
```
***
**Current/desired output**
Setting aside the readability of this code (it's a reduced example based on https://github.com/dataarts/dat.gui), a few things are not being documented as I had hoped:
1. Methods and properties could be distinguished somehow. Even sorting alphabetically, I think I'd want properties first and then methods, perhaps with subheaders.
2. The `@type` tag isn't reflected for any of the properties; no type information shows up.
3. I often see `@type` used in oneliners as `/** @type {number} Quantity of foo. */`. I'm not sure if that's actually valid JSDoc, but curious for your thoughts. Here, the description is ignored when written this way.
Related to https://github.com/documentationjs/documentation/issues/906 and https://github.com/documentationjs/documentation/issues/246.
Thanks for writing this tool! Let me know if changes for any of this would be reasonable or wanted.
**Other**
* What version of documentation.js are you using?: 5.3.3
* How are you running documentation.js (on the CLI, Node.js API, Grunt, other?): CLI
Contributor guide
Assessment
This issue has not been assessed yet.