ドキュメント

Documentation はサービスを記述するための情報を提供します。

例:

documentation:
  summary: >
    The Google Calendar API gives access
    to most calendar features.
  pages:
  - name: Overview
    content: (== include google/foo/overview.md ==)
  - name: Tutorial
    content: (== include google/foo/tutorial.md ==)
    subpages;
    - name: Java
      content: (== include google/foo/tutorial_java.md ==)
  rules:
  - selector: google.calendar.Calendar.Get
    description: >
      ...
  - selector: google.calendar.Calendar.Put
    description: >
      ...

Documentation はマークダウン構文で提供されます。標準のマークダウン機能に加えて、定義リスト、テーブル、フェンス付きコードブロックがサポートされます。セクションのヘッダーを指定でき、ドキュメント フラグメントが埋め込まれるコンテキストのセクションのネストに相対的に解釈されます。

IDL の Documentation は正規化時の設定を介してドキュメントとマージされます。この場合、設定ルールによって指定されるドキュメントは指定の IDL をオーバーライドします。

API プラットフォームに固有の複数の構文がドキュメント テキストでサポートされます。

プロト要素を参照するには、次の表記を使用できます。

[fully.qualified.proto.name][]

リンクに使用される表示テキストをオーバーライドするには、次の表記を使用できます。

[display text][fully.qualified.proto.name]

テキストをドキュメントから除外するには、次の表記を使用します。

(-- internal comment --)

ドキュメントではいくつかのディレクティブを使用できます。ディレクティブは適切に識別されるために単一の行に記述される必要があります。include ディレクティブには外部ソースからのマークダウン ファイルが含まれます。

(== include path/to/file ==)

resource_for ディレクティブは REST ビューでメッセージをコレクションのリソースであるとマークします。これが指定されていない場合、ツールはコレクション内の操作からリソースを推定しようとします。

(== resource_for v1.shelves.books ==)

ディレクティブ suppress_warning はドキュメントに直接は影響せず、サービス設定検証と共にドキュメント化されます。

JSON 表現 

{
  "summary": string,
  "pages": [
    {
      object(Page)
    }
  ],
  "rules": [
    {
      object(DocumentationRule)
    }
  ],
  "documentationRootUrl": string,
  "overview": string
}
フィールド
summary

string

サービスが行う処理の概要。プレーン テキストでのみ入力できます。

pages[]

object(Page)

ドキュメント セットの最上位ページ。

rules[]

object(DocumentationRule)

個々の API 要素に適用されるドキュメント ルールのリスト。

注: すべてのサービス構成ルールは「最後の 1 つが最優先」の順序に従います。
documentationRootUrl

string

ドキュメントのルートの URL。

overview

string

1 つの概要ページを宣言します。次に例を示します。


documentation:
  summary: ...
  overview: (== include overview.md ==)

これは次の宣言のショートカットです（pages スタイルを使用）。


documentation:
  summary: ...
  pages:
  - name: Overview
    content: (== include overview.md ==)

注: overview フィールドと pages フィールドの両方を指定することはできません。

Page

ドキュメントのページを表します。ページには、ネストされたドキュメント セット構造を表すサブページを含めることができます。

JSON 表現 

{
  "name": string,
  "content": string,
  "subpages": [
    {
      object(Page)
    }
  ]
}
フィールド
name

string

ページの名前。ページの URI や、ナビゲーションでのこのページへのリンクのテキストなどを生成するためのページの ID として使用されます。完全ページ名（ルートページ名から、. で連結されるこのページまでの名前）は、ドキュメントでページへの参照として使用できます。次に例を示します。


pages:
- name: Tutorial
  content: (== include tutorial.md ==)
  subpages:
  - name: Java
    content: (== include tutorial_java.md ==)

Java ページは、次のマークダウン参照リンクの構文を使用して参照できます ([Java][Tutorial.Java]）。
content

string

ページのマークダウン コンテンツ。次のコマンドを使用すると

(== include {path} ==)

マークダウン ファイルの内容を含めることができます。
subpages[]

object(Page)

このページのサブページ。ここで指定されるサブページの順序は、生成後のドキュメント セットで適用されます。

DocumentationRule

ドキュメント ルールは個々の API 要素に関する情報を提供します。

JSON 表現 

{
  "selector": string,
  "description": string,
  "deprecationDescription": string
}
フィールド
selector

string

セレクタはパターンのカンマ区切りリストです。各パターンは、ワイルドカードを示す "*" で終わる可能性のある要素の修飾名です。ワイルドカードは、パターンの末尾で、修飾名のコンポーネント全体についてのみ使用できます。たとえば "foo.*" は指定できますが、"foo.b*" や "foo.*.bar" は指定できません。該当するすべての要素のデフォルトを指定するには、パターン全体を表す "*" を使用します。

description

string

選択された API の説明。

deprecationDescription

string

選択された要素のサポート終了に関する説明。要素が deprecated とマークされている場合に入力できます。