web-dev-qa-db-ja.com

phpDocがオブジェクトの配列をパラメーターとして文書化する方法はありますか？

PhpDocで生成されたドキュメントでは、phpDocに、を使用して特定のパラメーターのカスタム型定義へのリンクを生成させることができます。

@param CustomType $variablename

そしてそれは素晴らしい働きをします。ただし、現在文書化しているコードには、CustomType []パラメーター、つまり前述のCustomTypeの配列が必要です。配列が必要であることをドキュメントに明確にしたいと思いますが、

@param CustomType[] $variablename

phpDocはタイプを認識しなくなったため、その定義にリンクできません。この場合、これは非常に重要です。提供する必要のあるかなり複雑なタイプを持つAPIを文書化しています。

私はこれに対していくつかの異なる構文を試しましたが、すべてエントリを個別の変数タイプとして扱うか、ドキュメントでブレークタイプの認識を行います。

これを除けば、パラメータノートに記載するだけですが、型内のパラメータの配列性を示す方が明確なようです。

[〜＃〜]編集[〜＃〜]

PhpDocumentor 2（DocBloxと統合）を使用すると、

@param CustomType[] $paramName

構文は機能し、@ Styxの回答に記載されているように、PhpStormはその構文での型ヒントをサポートしています。

受け入れられた回答は適切に更新されました。

arraysphpdoccustom-type
22
cori

新しいバージョンのPHPドキュメントサポート_/** @var sometype[] */_構文。さらに複雑：/** @var (sometype|othertype)[] */。 http://www.phpdoc.org/docs/ latest/guides/types.html＃arrays PHPStormもこの構文をサポートしています。

34
Styx

あなたができる最善のことは：

@param array $variablename an array of {@link CustomType} objects

これは、配列に含まれるものの期待値を示しながら、読者が$ variablenameの真のデータ型を理解するのに役立つはずです。

$ variablenameのメンバーを使用し、CustomTypeのプロパティ/メソッドが表示されることを期待する場合、これはIDEのオートコンプリートを支援するのに十分ではありません。現在、その動作を取得する方法は実際にはありません。

3
ashnazg

次の例を参照してください。 https://code.google.com/p/google-api-php-client/source/checkout ここで、は入力パラメータの配列構造について説明しています。

/**
  * Set the OAuth 2.0 access token using the string that resulted from calling authenticate()
  * or Google_Client#getAccessToken().
  * @param string $accessToken JSON encoded string containing in the following format:
  * {"access_token":"TOKEN", "refresh_token":"TOKEN", "token_type":"Bearer",
  *  "expires_in":3600, "id_token":"TOKEN", "created":1320790426}
  */


/**
  * Insert a new file. (files.insert)
  *
  * @param Google_DriveFile $postBody
  * @param array $optParams Optional parameters.
  *
  * @opt_param bool convert Whether to convert this file to the corresponding Google Docs format.
  * @opt_param string targetLanguage Target language to translate the file to. If no sourceLanguage is provided, the API will attempt to detect the language.
  * @opt_param string sourceLanguage The language of the original file to be translated.
  * @opt_param string ocrLanguage If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes.
  * @opt_param bool pinned Whether to pin the head revision of the uploaded file.
  * @opt_param bool ocr Whether to attempt OCR on .jpg, .png, or .gif uploads.
  * @opt_param string timedTextTrackName The timed text track name.
  * @opt_param string timedTextLanguage The language of the timed text.
  * @return Google_DriveFile
  */
2
Marko Novakovic

注：この回答は、他の回答を補完するものです。

オブジェクトの配列を文書化するには、_@param ClassName[] $classInstance Description_を使用できます。ただし、PHP 7では、引数の型宣言（型ヒント）を使用できます。この場合、型はarrayである必要があります。

例：

enter image description here

ヒント：declare(strict_types=1);も使用する必要があります

2
SandroMarques

http://www.phpdoc.org/docs/latest/guides/types.html のphpdocドキュメントノート

アレイ

未知のタイプの変数のコレクション。配列メンバーのタイプを指定することができます。詳細については、配列の章を参照してください。

そして...リンクも「配列に関する」章もありません。いいえ、これは今後の機能のようです。

1
William Entriken