loopbackio / loopbackio/loopback-next
docs: move API references to tsdoc
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- TypeScript
- Sterne
- 5.1k
- Forks
- 1.1k
- Ø Merge
- 2 T. 21 Std.
- Gemergte PRs (30 T.)
- 27
Beschreibung
As part of our adoption of the four-quadrant documentation system (see #5549 and #5718), we should move API reference material from markdown files in `site/docs` folder to tsdoc comments in the source code.
This story is a part of #5113 Documentation improvements 2020Q3.
## Acceptance criteria
List of places to modify:
- [ ] https://loopback.io/doc/en/lb4/Server.html#rest-options
- [ ] The page "Model" contains reference-like content for model/property metadata mixed with guide-like content. We should rework the content into proper guides (recipes for achieving specific outcomes) and move reference description of different metadata options into tsdocs.
- [ ] https://loopback.io/doc/en/lb4/Model.html#supported-entries-of-model-definition
- [ ] https://loopback.io/doc/en/lb4/Model.html#unsupported-entries
- [ ] https://loopback.io/doc/en/lb4/Model.html#property-decorator
- [ ] https://loopback.io/doc/en/lb4/Model.html#id-properties
- [ ] https://loopback.io/doc/en/lb4/Model.html#data-mapping-properties
- [ ] https://loopback.io/doc/en/lb4/Model.html#supported-json-keywords
- [ ] http://loopback.io/doc/en/lb4/Creating-crud-rest-apis.html#model-configuration-options
- [ ] https://loopback.io/doc/en/lb4/Using-database-transactions.html#isolation-levels
- [ ] The page "Interceptors" contains reference-like content with code snippets showing the classes & interfaces including tsdoc. Let's find a better way how to present this information, leverage existing API doc pages and avoid duplication of content.
- [ ] https://loopback.io/doc/en/lb4/Interceptors.html#invocation-context
- [ ] https://loopback.io/doc/en/lb4/Interceptors.html#source-for-an-invocation
- [ ] The page "Life cycle" contains reference-like content with code snippets the classes & interfaces including tsdoc. Let's find a better way how to present this information, leverage existing API doc pages and avoid duplication of content.
- [ ] https://loopback.io/doc/en/lb4/Life-cycle.html#graceful-shutdown
- [ ] https://loopback.io/doc/en/lb4/Life-cycle.html#the-lifecycleobserver-interface
- [ ] https://loopback.io/doc/en/lb4/Life-cycle.html#observer-groups (`export type LifeCycleObserverOptions`)
- [ ] The pages grouped under [Decorators](https://loopback.io/doc/en/lb4/Decorators_repository.html) are reference guides. Let's move their content into tsdocs and update "Decorators" page to act as a sign post linking to the API docs. For each page we have now, create a section in "Decorators" page and list the relevant decorators there.
- [ ] [OpenAPI decorators](https://loopback.io/doc/en/lb4/Decorators_openapi.html)
- [ ] [Dependency Injection decorator](https://loopback.io/doc/en/lb4/Decorators_inject.html)
- [ ] [Authentication decorator](https://loopback.io/doc/en/lb4/Decorators_authenticate.html)
- [ ] [Service decorator](https://loopback.io/doc/en/lb4/Decorators_service.html)
- [ ] [Repository decorators](https://loopback.io/doc/en/lb4/Decorators_repository.html)
- [ ] The page "Context" contains reference-like content with code snippets the classes & interfaces including tsdoc. Let's find a better way how to present this information, leverage existing API doc pages and avoid duplication of content.
- [ ] https://loopback.io/doc/en/lb4/Context.html#context-events
- [ ] https://loopback.io/doc/en/lb4/Context.html#context-observers
- [ ] https://loopback.io/doc/en/lb4/Binding.html#binding-events
- [ ] https://loopback.io/doc/en/lb4/Dependency-injection.html#additional-inject-or-sugar-decorators -- leverage the new "Decorators" page
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Beginne mit der Durchsicht der aufgeführten Seiten in site/docs und des zugehörigen Kontexts aus #5549 und #5718. Vergleiche die referenzartigen Abschnitte mit der vorhandenen API-Dokumentation, insbesondere für Model, Interceptors, Life cycle, Context und Decorators. Abgeschlossen ist die Aufgabe, wenn das aufgeführte Referenzmaterial in tsdoc enthalten ist, doppelte Snippets behandelt sind und die Decorators-Seite auf die relevante API-Dokumentation verweist.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- typescript
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 5/5
- Geschätzter Aufwand
- Über eine Woche
- Aktivitätsstatus
- Veraltet
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 25/100