loopbackio / loopbackio/loopback-next

docs: move API references to tsdoc

Offen
#5,778 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Docs epic feature
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

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Ö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

Neue Issues direkt in Ihr Postfach

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