ドキュメント

ここでは、API にインライン ドキュメントを追加するためのガイドラインを示します。ほとんどの API には概要、チュートリアル、より高度なリファレンス ドキュメントも含まれますが、それらはこの設計ガイドの対象外となっています。API、リソース、メソッドの命名については、命名規則をご覧ください。

コメントの形式

通常のプロトコル バッファの // コメント形式を使用してコメントを .proto ファイルに追加します。

// Creates a shelf in the library, and returns the new Shelf.
rpc CreateShelf(CreateShelfRequest) returns (Shelf) {
  option (google.api.http) = { post: "/v1/shelves" body: "shelf" };
}

サービス構成のコメント

.proto ファイルにドキュメント コメントを追加する代わりに、YAML サービス構成ファイルで API にインライン ドキュメントを追加できます。両方のファイルで同じ要素が記述されている場合は、このファイルのドキュメントが .proto ファイルのドキュメントよりも優先されます。

documentation:
  summary: Gets and lists social activities
  overview: A simple example service that lets you get and list possible social activities
  rules:
  - selector: google.social.Social.GetActivity
    description: Gets a social activity. If the activity does not exist, returns Code.NOT_FOUND.
...

複数のサービスによって同じ .proto ファイルが使用され、サービス固有のドキュメントを提供する場合は、このアプローチを使用することが必要になる場合があります。YAML ドキュメント ルールでは、API の説明にさらに詳しい overview を追加することもできます。ただし、一般的には、.proto にドキュメント コメントを追加することをおすすめします。

.proto コメントと同様に、Markdown を使って YAML ファイルのコメントに追加の書式を設定できます。

API の説明

API の説明は、API でできることを記述する能動態動詞で始まるフレーズです。.proto ファイルでは、次の例のように、API の説明は対応する service にコメントとして追加します。

// Manages books and shelves in a simple digital library.
service LibraryService {
...
}

API の説明の例をさらにいくつか示します。

  • Shares updates, photos, videos, and more with your friends around the world.
  • Accesses a cloud-hosted machine learning service that makes it easy to build smart apps that respond to streams of data.

リソースの説明

リソースの説明は、リソースが表すものを記述する部分文です。詳細を追加する必要がある場合は、追加の文を使用します。.proto ファイルでは、次の例のように、リソースの説明は対応するメッセージ タイプにコメントとして追加します。

// A book resource in the Library API.
message Book {
  ...
}

リソースの説明の例を次に示します。

  • A task on the user's to-do list. Each task has a unique priority.
  • An event on the user's calendar.

フィールドとパラメータの説明

次の例に示すように、フィールドまたはパラメータの定義を記述する名詞句です。

  • The number of topics in this series.
  • The accuracy of the latitude and longitude coordinates, in meters. Must be non-negative.
  • Flag governing whether attachment URL values are returned for submission resources in this series. The default value for series.insert is true.
  • The container for voting information. Present only when voting information is recorded.
  • Not currently used or deprecated.

フィールドとパラメータの説明

  • 境界を明確に記述する必要があります(つまり、有効なものと有効でないものを明確にする必要があります。エンジニアはサービスの解読に最善を尽くしますが、不明な情報を明らかにするために基礎となるコードを読むことができないので注意してください)。
  • デフォルト値またはデフォルトの動作、つまり、値が指定されない場合にサーバーが行う処理を指定する必要があります。
  • 名前やパスなどの文字列の場合は、構文を記述し、許容される文字と必要なエンコードを一覧表示します。例:
    • セット内の 1~255 文字 [A-a0-9]。
    • / で始まる、RFC 2332 の規則に従う有効な URL パス文字列。最大長は 500 文字です。
  • 可能な限り、例の値を提供します。
  • フィールド値が requiredinput onlyoutput only の場合は、フィールドの説明の最初にドキュメント化する必要があります。デフォルトでは、すべてのフィールドとパラメータは省略可能です。例:
message Table {
  // Required. The resource name of the table.
  string name = 1;
  // Input only. Whether to dry run the table creation.
  bool dryrun = 2;
  // Output only. The timestamp when the table was created. Assigned by
  // the server.
  Timestamp create_time = 3;
  // The display name of the table.
  string display_name = 4;
}

メソッドの説明

メソッドの説明は、メソッドがどのような効果を持ち、どのリソース上で動作するかを示す文です。通常、三人称の現在時制の動詞(つまり、「s で終わる動詞」)で始まります。詳細を追加する必要がある場合は、追加の文を使用します。次に例を示します。

  • Lists calendar events for the authenticated user.
  • Updates a calendar event with the data included in the request.
  • Deletes a location record from the authenticated user's location history.
  • Creates or updates a location record in the authenticated user's location history using the data included in the request. If a location resource already exists with the same timestamp value, the data provided overwrites the existing data.

すべての説明のチェックリスト

各説明が簡潔で不足がなく、API に関する追加情報を持たないユーザーが理解できることを確認してください。ほとんどの場合、明白なことを再記述するだけでは十分ではありません。たとえば、series.insert メソッドの説明は、単に「Inserts a series」とはしません。名前はわかりやすくする必要がある一方で、読者が説明を読むのは、名前自体が示すよりも多くの情報を必要とするからです。説明で付け加える情報がわからない場合は、次の質問のうち、関連するすべてのものについて、回答を考えてみます。

  • これは何ですか?
  • 成功するとどうなりますか?失敗するとどうなりますか?何がどのように失敗する原因になりますか?
  • べき等ですか?
  • 単位は何ですか?(例: メートル、度、ピクセル)
  • どのような範囲の値が受け入れられますか?範囲は包含ですか排他ですか?
  • どのような副作用がありますか?
  • どのように使用しますか?
  • 破損させる可能性がある一般的なエラーは何ですか?
  • 常に存在しますか?(例: 「投票情報のコンテナ。投票情報が記録されている場合にのみ存在します」)
  • デフォルト設定がありますか?

規則

ここでは、テキスト記述とドキュメントの使用法の規則を示します。たとえば、識別子について説明するときは、「Id」や「id」ではなく、「ID」(すべて大文字)を使用します。データ形式を指すときは、「Json」や「json」ではなく、「JSON」を使用します。フィールド名とパラメータ名はすべて code font で表示します。リテラル文字列値は code font で引用符に入れます。

  • ID
  • JSON
  • RPC
  • REST
  • property_name または "string_literal"
  • true / false

要求レベル

期待や状態の要求レベルを設定するには、次の用語を使用します。must、must not、required、shall、shall not、should、should not、recommended、may、optional

意味は RFC 2119 で定義されています。API のドキュメントに RFC の抜粋の文を含めることができます。

デベロッパーに柔軟性を提供する一方で、どの用語が要件を満たすかを判断します。API で他の選択肢が技術的に機能する場合は、must のような絶対的な用語を使用しないでください。

言語スタイル

命名規則の場合と同様に、ドキュメントのコメントを記述するときは、単純で整合性のある語彙とスタイルを使用することをおすすめします。コメントは英語を母語としない読者が理解できる必要があるため、業界用語、スラング、複雑な暗喩、ポップ カルチャーへの言及や、その他すべての翻訳困難なものは避けてください。コメントを読むデベロッパーに直接語りかける、わかりやすくプロフェッショナルなスタイルを使用し、できるだけ簡潔にします。ほとんどの読者の目的は、ドキュメントを読むことではなく、API を使用して何かをする方法を見つけることであることを忘れないようにします。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...