11

個々のパラメーターではなく、単一の構成配列を取る関数を文書化するための構文はありますか?

私は特に、これに似たメカニズムを使用する CodeIgniter スタイルのライブラリについて考えています。

<?php

//
// Library definition
//

class MyLibrary {
  var $foo;
  var $bar;
  var $baz;
  // ... and many more vars...


  /* Following is how CodeIgniter documents their built-in libraries,
   * which is mostly useless.  AFAIK they should be specifying a name
   * and description for their @param (which they don't) and omitting
   * @return for constructors 
   */

  /** 
   * @access public
   * @param array
   * @return void
   */
  function MyLibrary($config = array()) {
    foreach ($config as $key => $value) {
      $this->$key = $value;
    }
  }
}

//
// Library usage:
//

// Iniitialize our configuration parameters
$config['foo'] = 'test';
$config['bar'] = 4;
$config['baz'] = array('x', 'y', 'z');

$x = new MyLibrary($config);

?>

だから私の質問は、純粋にテキストの説明を超えて構成配列を文書化するサポートされている方法はありますか? 実際@param [type] [name] [desc]に、PHPDoc が有用な値を解析できる適切なものを指定していますか?

余談ですが、CodeIgniter は実際には、上記のように $config 配列を介して渡された値で独自の値を上書きするだけであり、効果的にプライベート メンバーを上書きできます。私はファンではありませんが、私はそれに立ち往生しています。

4

7 に答える 7

11

これを文書化する「良い」方法を見たことがありません-そして、IDE （Eclipse PDTなど）でパラメータを示唆するために使用できるものを見たこともありません:-(

私は「あなたのフレームワークがするようにする」と言ったでしょうが、あなたが言ったように、ここでそれがすることは十分ではありません...


ただし、可能なキーのクイック/ソートリストは、何もないよりはましかもしれません。このようなビット:

@param array $config [key1=>int, otherKey=>string]

phpDocumentor または IDE によってどのように解釈されるかわかりませんが、試してみる価値はありますか?

これは、ところで、私がこの種のパラメーターを渡す方法を避ける傾向がある理由の 1 つです。少なくとも、メソッドへの (オプションの) パラメーターが多すぎない場合はそうです。

于 2010-01-05T21:12:46.530 に答える
4

配列の正しい配列 @param 表記は、PHPlintで指定されているとおりです。

これを使用して、構成配列を便利な方法で文書化できます。

例：

 /**
 * Does stuff
 *
 * @param array[int|string]array[string]Object $config
 *
 * @return array[int]string
 */
public function foo(array $config)
{
    // do stuff here

    return array('foo', 'bar', 'baz');
}
于 2010-10-21T13:47:57.150 に答える
2

あなたはこれを行うことができます：

/**
 * @param 配列 $param1
 * @param 文字列 $param1['hello']
 */
関数ねえ($param1)
{
}

そしてnetbeansはそれを拾いますが、phpdocはドキュメントを台無しにします

于 2011-08-29T22:34:50.583 に答える
1

私はいつも<pre>このような状況でタグを使用します。元。：

/**
 * @param array $ops An array of options with the following keys:<pre>
 *     foo: (string) Some description...
 *     bar: (array) An array of bar data, with the following keys:
 *         boo: (string) ...
 *         far: (int) ...
 *     baz: (bool) ...
 * </pre>
 */

私が使用したほとんどの IDE とドキュメント ジェネレーターは、これを合理的な方法でレンダリングしているように見えますが、もちろん、配列パラメーターの型チェックや検査は提供していません。

于 2012-06-01T19:19:48.240 に答える
1

現在、これを行うための「公式」(「複数のツールでサポートされている」など) の方法はありません。

PHP FIG は現在、 https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussionで議論しています。

于 2012-10-04T08:14:14.740 に答える
0

クラスを利用しました。

<?php
class MyLibrary {
    var $foo;
    var $bar;
    var $baz;

    /**
     * @param MyLibraryConfig|null $config
     */
    function MyLibrary( $config = null ) {
        if ( isset( $config->foo ) ) {
            $this->foo = $config->foo;
        }
        if ( isset( $config->baz ) ) {
            $this->baz = $config->baz;
        }
        if ( isset( $config->bar ) ) {
            $this->bar = $config->bar;
        }
    }
}

/**
 * @property string $foo
 * @property int    $bar
 * @property array  $baz
 */
class MyLibraryConfig {
}

それはかなりうまく機能しますが、主な問題は、コードに特定のクラスが散らばっていることです。それらはネストできるため、構成の一部を再利用できます。

于 2012-10-15T09:52:32.920 に答える
0

テキストによる説明は、どの程度完全であっても、実際には唯一のオプションです。$array必要に応じて読みやすくすることはできますが、コード分析ツール (phpDocumentor、IDE サポート) は、実行時に実際にどのように構造化されているかを知る方法がありません。

このようにコードを書くことは、コーディングの利便性とコードの読みやすさを交換するという多くのコメント者に同意します。

于 2010-01-06T21:00:28.297 に答える