loopbackio / loopbackio/loopback-next

docs: move API references to tsdoc

Ouverte
#5,778 1 commentaire 0 réactions 0 personnes assignées Voir sur GitHub

Personne n'a encore pris cette issue.

Docs epic feature
Langage dominant
TypeScript
Étoiles
5.1k
Forks
1.1k
Merge moyen
2 j 21 h
PR mergées (30 j)
27

Description

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

Guide de contribution

Ouvrir le guide de contribution

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Piste de recherche

Commencez par examiner les pages indiquées dans site/docs et le contexte associé de #5549 et #5718. Comparez les sections de type référence avec la documentation API existante, en particulier pour Model, Interceptors, Life cycle, Context et Decorators. Le travail est terminé lorsque le matériel de référence indiqué est représenté dans tsdoc, que les extraits dupliqués sont traités et que la page Decorators contient un lien vers la documentation API pertinente.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

Évaluation

Stack technique
typescript
Domaine
documentation
Type d'issue
Documentation
Difficulté
5/5
Temps estimé
Plus d'une semaine
Activité
À l'abandon
Clarté
Plutôt claire
Accessibilité débutants
25/100

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.