loopbackio / loopbackio/loopback-next

docs: move API references to tsdoc

オープン
#5,778 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

Docs epic feature
主要言語
TypeScript
スター
5.1k
フォーク
1.1k
平均マージ
2日 21時間
マージ済み PR(30日)
27

説明

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

コントリビューションガイド

コントリビューションガイドを開く

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

調査の方向性

まず site/docs に一覧されているページと、#5549 および #5718 に関連するコンテキストを確認します。参照資料に近いセクションを既存の API ドキュメントと比較します。特に Model、Interceptors、Life cycle、Context、Decorators を対象とします。一覧されたリファレンス資料が tsdoc に反映され、重複したスニペットが対処され、Decorators ページから関連する API ドキュメントにリンクされていれば完了です。

索引モデルが issue の本文から書いたものです。

評価

技術スタック
typescript
領域
documentation
issue の種類
ドキュメント
難易度
5/5
見積もり時間
1週間以上
活発さ
停滞
明瞭さ
おおむね明確
初心者へのやさしさ
25/100

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。