가변 길이의 인수 배열에 대한 PHPDOC

StackOverflow https://stackoverflow.com/questions/2009122

문제

개별 매개 변수가 아닌 단일 구성 배열을 취하는 함수를 문서화하기위한 구문이 있습니까?

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 배열을 통해 전달 된 것들과 자체 값을 덮어 쓰며 개인 구성원을 효과적으로 허용합니다. 나는 팬이 아니지만 나는 그것에 붙어 있습니다.

도움이 되었습니까?

해결책

나는 이것을 문서화하는 "좋은"방법을 본 적이 없으며 Ides가 사용할 수있는 것을 본 적이 없습니다. (예 : Eclipse PDT) 하나를 암시하는 매개 변수의 경우 :-(

나는 말했다 "프레임 워크가 좋아요", 그러나 당신이 말했듯이, 여기에서하는 일은 충분하지 않습니다 ...


아마도 가능한 키의 빠른/정렬 목록은 아무것도 아닌 것보다 낫을 수 있습니다. 조금은 다음과 같습니다.

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

Phpdocumentor 또는 IDE에 의해 어떻게 해석 될지 확실하지 않지만 시도해 볼 가치가 있습니까?

이것은 BTW입니다. 적어도 방법에 너무 많지 않은 (선택 사항) 매개 변수가 없을 때 이러한 종류의 매개 변수를 전달하는 방법을 피하는 이유 중 하나입니다.

다른 팁

배열에 대한 올바른 배열 @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');
}

당신은 이것을 할 수 있습니다 :

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

NetBeans는 그것을 선택하지만 PhPDOC는 문서를 엉망으로 만듭니다.

나는 항상 사용합니다 <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 및 문서 생성기는 합리적인 방식으로이를 렌더링하는 것처럼 보이지만 물론 배열 매개 변수의 유형 확인 또는 검사를 제공하지는 않습니다.

현재 "공식적인"( '여러 도구에 의해 지원되는 것과 같이)는이 작업을 수행 할 수 없습니다.

PHP 무화과는 현재에서 논의하고 있습니다. https://groups.google.com/d/topic/php-fig/o4ko1xsgtaw/discussion

원하는 정도의 완전성에 대한 텍스트 설명은 실제로 유일한 선택입니다. 원하는만큼 읽을 수 있지만 코드 분석 도구 (Phpdocumentor, IDE 지원)는 어떻게 귀하의 $array 실제로 런타임에 구성됩니다.

나는 코드를 작성하면 코드가 레그 리니에 대한 편의를 코딩하는 것을 교환한다는 많은 주석가들과 동의합니다.

수업을 사용했습니다.

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

그것은 상당히 잘 작동합니다. 주요 문제는 코드가 특정 클래스로 가득 차 있다는 것입니다. 구성의 일부를 재사용 할 수 있도록 중첩 될 수 있습니다.

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top