loopbackio / loopbackio/loopback-next
docs: move API references to tsdoc
まだ誰も着手していません。
- 主要言語
- 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
コントリビューションガイド
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
調査の方向性
まず site/docs に一覧されているページと、#5549 および #5718 に関連するコンテキストを確認します。参照資料に近いセクションを既存の API ドキュメントと比較します。特に Model、Interceptors、Life cycle、Context、Decorators を対象とします。一覧されたリファレンス資料が tsdoc に反映され、重複したスニペットが対処され、Decorators ページから関連する API ドキュメントにリンクされていれば完了です。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- typescript
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 停滞
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 25/100