기능을 설정하고 무제한 매개 변수를 문서화하는 올바른 방법은 무엇입니까?

배경 : 메서드에 전달 된 모든 값을 내 클래스에 추가하는 addAll 메서드를 만듭니다. 여기에 내가 생각했던 것이있다 :기능을 설정하고 무제한 매개 변수를 문서화하는 올바른 방법은 무엇입니까?

public function addAll() { 
    if(func_num_args()===0) { 
     throw new BadMethodCallException(get_class($this).'::addAll() must have arguments.'); 
    } 

    $args = func_get_args(); 

    foreach($args as &$arg) { 
     $this->add($arg); 
    } 
}

그리고 그것은 훌륭하게 작동한다. 그런 다음 phpDocumentor로 문서화해야합니다 :

/** 
* @param mixed ... All of the values to add. 
*/

. . . 솔직히 말해서, 존재하지 않기 때문에 나는 @param이라는 이름을 가지고 있지 않습니다.

질문 : 어떻게 이런 식으로 구성하고 정의합니까?

나는 그것이 전달 적어도 하나 개의 값을 갖고 싶어하기 때문에, 나는이 함께했다하지만 확실하지 오전 : $value 직접 사용되지 않습니다 때문에

가

/** 
* @param mixed $value,... All of the values to add. 
*/ 
public function addAll($value) { 
    $args = func_get_args(); 

    foreach($args as &$arg) { 
     $this->add($arg); 
    } 
}

그것은 너무 잘못된 것 같다. . .

또한 이미 add을 추가 했으므로 addAll은 의미 상 적어도 두 개의 매개 변수가 필요하지 않습니까? 그 정의 및 문서화에 대해 귀하는 무엇을 권하고 싶습니까?

출처

2011-09-06 Levi Morrison

나는 두 번째 예제를 사용하고 추가로의 클래스 속성을 언급 것 클래스의 시작 부분이지만 코딩 컨벤션과 관련이 있다고 생각합니다. 또한 다음을 참조하십시오 : http://stackoverflow.com/questions/2871204/how-to-document-an-accessor-mutator-method-in-phpdoc-javadoc – feeela

두 번째 예제는 표시된 것처럼 "무제한 인수"를 처리하기위한 시연 된 사용법에 적합합니다. phpDocumentor 매뉴얼 - http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html – ashnazg

@ashnazg이 상황을 피하기 위해 코드를 모두 재구성했습니다. 내 생각에이 사건이 발생하지 않았다면 프로그래밍 논리가 잘못되었을 수도 있습니다. –

답변 : @example 태그를 사용하십시오.

나는 또한 내 설정을 변경, 그리고 PHP 유용성을 몰수하지 않고 제공하는 무엇을 활용하는 가장 좋은 방법이 될 것 같다 :

/** 
* @param mixed $values Either an array of values to add, or multiple values 
* @example 
* 
* $object->add('1'); 
* $object->add('1','2'); 
* $object->add(array('1','2')); 
* 
* @return type 
*/ 
public function add($values=null) { 
    if (is_array($values)) { 
     return $this->addAll($values); 
    } else { 
     return $this->addAll(func_get_args()); 
    } 
}

출처

2011-09-30 20:58:53

기능을 설정하고 무제한 매개 변수를 문서화하는 올바른 방법은 무엇입니까?

답변

관련 문제