documentationjs / documentationjs/documentation

More detailed markdown template

Offen
#593 6 Kommentare 1 Reaktion 0 zugewiesene Personen Auf GitHub ansehen
Vorherrschende Sprache
JavaScript
Sterne
5.8k
Forks
481
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

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:
screen shot 2016-11-11 at 07 01 54

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.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne damit, den Einstiegspunkt der Markdown-Vorlage zu finden und seine aktuelle Ausgabe mit dem vorgeschlagenen getData-Beispiel zu vergleichen. Als erledigt gilt die Aufgabe, wenn die Markdown-Ausgabe Funktionen, Felder, Konstanten und Ereignisse unterscheidet und die angeforderten Informationen zur Funktionssignatur enthält, ohne die dargestellten Parameter- und Rückgabebereiche zu beeinträchtigen.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
javascript
Bereich
documentation
Issue-Typ
Feature
Schwierigkeit
3/5
Geschätzter Aufwand
1-2 Tage
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
38/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.