Argüman değişken uzunlukta diziler için PHPDoc

7 Cevap php

Yerine bireysel parametrelerin daha tek bir yapılandırma dizi çekmek fonksiyonları belgelemek için bir sözdizimi var mı?

Ben özellikle buna benzer bir mekanizma kullanmak CodeIgniter tarzı kütüphaneler, düşünüyorum:

<?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);

?>

Yani benim soru, sadece tamamen metinsel açıklamalar ötesinde yapılandırma dizi belgeleyen bazı supprted yolu var mı? Aslında belirterek uygun bir @param [type] [name] [desc] PHPDoc yararlı değerleri ayrıştırmak için izin verir mi?

Bir kenara, CodeIgniter gerçekten sadece etkili özel üyeleri yenmek için izin, yukarıdaki gibi $ config dizisi aracılığıyla iletilen bu ile kendi değerlerin üzerine gelmez. Ben bir hayranı değilim, ama onunla şaşırıp.

7 Cevap

Ben bu belgeleyen herhangi bir "iyi" bir yol görmedim - ve ben (such as Eclipse PDT) ya :-( ima parametreler için IDE tarafından kullanılan olabilir şey görmedim

Ben "do like your framework does" dedi, ama dediğin gibi, ne yapar, burada, yeterince iyi değil olurdu ...


Maybe a quick/sort list of possible keys might be better than nothing, though ; a bit like this :

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

Değil phpDocumentor veya bir IDE tarafından yorumlanır olacaktır ... Ama bir cami olabilir nasıl emin?

This is, btw, one reason why I tend to avoid that kind of way of passing parameters -- at least when there are not too many (optional) parameters to a method.

PHPlint belirtildiği gibi diziler için doğru dizisi @ param gösterimi

Yararlı bir şekilde bir yapılandırma dizi belgelemek için kullanabilirsiniz:

Example:

 /**
 * 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');
}

Bunu yapabilirsiniz:

/**
 * @param array $param1
 * @param string $param1['hello']
 */
function hey($param1)
{
}

ve netbeans onu almak olacak ama phpdoc belgelere messes

İstediğiniz bütünlüğü ne derecede bir metin açıklaması, gerçekten tek seçenek olduğunu. Istediğiniz kadar o kadar okunaklı hale getirebilir, ancak kod analiz araçları (phpDocumentor, IDE desteği) ve $array aslında zamanında nasıl yapılandırıldığını bilmek için hiçbir yolu yoktur.

Ben birçok commenters katılıyorum bu kod okunabilirliği için kolaylık kodlama kod yazma bu şekilde değişim.

Ben her zaman bu gibi durumlarda <pre> etiketleri kullanın. Ör.:

/**
 * @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>
 */

Ben kullanmış çoğu IDE ve belgeler jeneratörler tabii ki dizi parametreleri herhangi bir tür denetlemesi veya muayene vermeyin olsa, makul bir şekilde bu hale görünüyor.

Hiçbir "resmi" Bunu yapmak için bir yol ('çoklu araçları tarafından desteklenen' gibi) bulunmamaktadır.

PHP Şekil https://groups.google.com/d/topic/php-fig/o4ko1XsGtAw/discussion de şu an bunu tartışıyor

Ben sınıfları kullandım.

<?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 {
}

Bu oldukça iyi çalışıyor, asıl sorun, kod özel sınıflar ile çevrili hale olmasıdır. Yapılandırma parçaları yeniden kullanılabilir böylece iç içe olabilir.

etiketler