documentationjs / documentationjs/documentation

Property/method distinction and @type support.

Open
#962 2 comments 1 reaction 0 assignees View on GitHub
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

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.