ドキュメントJsonデータ

マークダウンでフォーマットされた自動生成されたreadmeファイルは便利ですが、すべてのドキュメントをjsonデータの形式で取得したほうがよいシナリオもあります。ドキュメントをjsonとしてビルドするには、 --docs-jsonフラグを使用し、その後にjsonファイルを書き込む場所のパスを続けます。

  scripts: {
    "docs.data": "stencil build --docs-json path/to/docs.json"
  }

別のオプションは、ビルドごとにこのファイルを自動生成するために、 docs-json出力ターゲットをstencil.config.tsに追加することです。

import { Config } from '@stencil/core';

export const config: Config = {
  outputTargets: [
    {
      type: 'docs-json',
      file: 'path/to/docs.json'
    }
  ]
};

JSON出力のTypeScript宣言を確認してください: https://github.com/ionic-team/stencil/blob/main/src/declarations/stencil-public-docs.ts

CSS変数

Stencilは、css/scssファイル内のjsdocスタイルのコメントを介してCSS変数を指定すると、CSS変数も文書化します。

/**
 * @prop --background: ボタンの背景
 * @prop --background-activated: アクティブ化されたときのボタンの背景
 * @prop --background-focused: フォーカスされたときのボタンの背景
 */

スロット

スロットは、コンポーネントデコレータの上のドキュメントコメントに @slotタグを追加することで文書化できます。

/**
 * @slot slotの名前 - slotの説明
 * @slot buttonContent - ボタンのコンテンツ用のスロット
 */

使用法

コンポーネントの usageサブディレクトリにある.mdファイルのコンテンツは、生成されたjsonの usageプロパティに追加されます。

src/
  components/
    my-component/
      usage/
        usage-example.md
        another-example.md
      my-component.css
      my-component.tsx

カスタムJSDocsタグ

事前定義されたJSDocタグを読み取ることに加えて、ユーザーは独自のカスタムタグを提供できます。これもJSONデータに含まれます。これにより、チームが独自のドキュメントと規則を提供して、JSONデータ内に構築することが容易になります。たとえば、次のようにソースコードにコメントを追加した場合：

/**
 * @myDocTag someName - some value
 * @myOtherDocTag someOtherName - some other name
 */

最終的には次のようなJSONデータになります。

"docsTags": [
  {
    "text": "someName - some value",
    "name": "myDocTag"
  },
  {
    "text": "someOtherName - some other name",
    "name": "myOtherDocTag"
  }
],