documentationjs / documentationjs/documentation
Property/method distinction and @type support.
- Lingua principale
- JavaScript
- Stelle
- 5.8k
- Fork
- 481
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
**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
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia eseguendo il comando CLI documentato con l'esempio foo.js fornito e confronta il Markdown generato con l'output desiderato. Analizza come vengono rappresentate le proprietà, i metodi e le annotazioni @type, inclusi i commenti @type su una sola riga; il lavoro è completato quando le distinzioni, le informazioni sui tipi e le descrizioni richieste sono riflesse nella documentazione generata.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- javascript
- Ambito
- documentation
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 40/100