documentationjs / documentationjs/documentation
More detailed markdown template
- Lingua principale
- JavaScript
- Stelle
- 5.8k
- Fork
- 481
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Descrizione
Let me start off by saying that I am impressed with how smooth documentationjs works. I started fiddling around with it the other day and it's really impressive, especially to be able to output directly to a README.md.
I would like to suggest an improvement to the markdown template. The improvement mainly serves two functions:
1. Make it easier to distinguish functions from fields or constants, currently there's no visible difference between a `@constant`, `@function` or `@event`
2. More information density in the function header
When generating html docs from the following code:
```
/**
* Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.
* @param {Object} options
* @param {Boolean} [options.forceReload=false] Force reload from server, otherwise uses local cache
* @return {Promise} Promise with user data if success, failure reason otherwise
*/
function getData(options) {
...
}
```
this is the result:

This is the benchmark ☝️
When generating to markdown this is the result:
-----
# getData
Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.
**Parameters**
- `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `options.forceReload` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** Force reload from server, otherwise uses local cache (optional, default `false`)
Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Promise with user data if success, failure reason otherwise
-----
I suggest to improve it to:
-----
# getData(options: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)
Gets user data. If forceReload is provided it will force check from backend, otherwise it will use locally cached data.
**Parameters**
- `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)**
- `options.forceReload` **\[[Boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)]** Force reload from server, otherwise uses local cache (optional, default `false`)
Returns **[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)** Promise with user data if success, failure reason otherwise
-----
If this seems like a reasonable improvement to you I can try to fix it myself with a PR if I could be pointed in the right direction.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia individuando il punto di ingresso del modello markdown e confrontando il suo output attuale con l’esempio getData proposto. Il lavoro è completato quando l’output markdown distingue funzioni, campi, costanti ed eventi e include le informazioni richieste sulla firma della funzione senza introdurre regressioni nelle sezioni mostrate relative ai parametri e ai valori restituiti.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- javascript
- Ambito
- documentation
- Tipo di issue
- Funzionalità
- Difficoltà
- 3/5
- Tempo stimato
- 1-2 giorni
- Stato di attività
- Ferma
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 38/100