오버로드 된 방법으로 PHPDOC를 사용하는 방법은 무엇입니까?

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

문제

PHP 클래스가 호출되었다고 가정 해 봅시다 색깔, 생성자는 다양한 매개 변수를 수락합니다.

// hex color
$myColor = new Color('#FF008C');

// rgb channels
$myColor = new Color(253,15,82);

// array of rgb channels
$myColor = new Color(array(253,15,82));

// X11 color name
$myColor = new Color('lightGreen');

PHPDOC를 사용하여 생성자 및 이와 같은 다른 방법에 대한 API 문서를 만드는 방법은 무엇입니까?

오버로드 된 방법으로 PHPDOC를 사용하는 방법은 무엇입니까?

class Color {

    /**
     * Constructor
     * what should be here?
     */
    public function __construct() {
        /* CODE */
    }

}
도움이 되었습니까?

해결책

가변 길이 인수를 허용하기 때문에 두 가지 방법이 있습니다.

허용 인수는 매개 변수입니다.

/**
 * @param mixed $arg1 ... description
 * @param mixed $arg2 ... description
 * @param mixed $arg3 ... description
 */
 public function __construct() {}

또는 나는 단순히 몇 가지 예제에 대해 설명을 제공 할 것입니다.

/**
 * Explanation of different expected argument combinations.
 */
public function __construct() {}

또 다른 대안은 예제 중 하나만 하나 이상의 인수를 가지고 있기 때문에 메소드 서명의 인수를 단순히 마지막 2를 선택하는 것만으로 정의하는 것입니다. 이와 같이:

/**
 * @param mixed $arg1 ...
 * @param int $arg2 ...
 * @param int $arg3 ...
 */
public function __construct($arg1, $arg2 = null, $arg3 = null) {}

다른 팁

내 관점만으로도 처음에는 여러 생성자가 없어야합니다. 생성자는 IF/Else -Ladders로 가득 차 있습니다. 특히 좋은 생각이 아닙니다. 색깔.

대신 이런 식으로 시도해 보도록 격려합니다.

class Color
{
    protected function __construct($r, $g, $b)
    { ... }

    public static function fromHex($hex) {
        return new Color(...);
    }

    public static function fromRGB($r, $g, $b) { ... }

    public static function fromArray(array $rgb) { ... }

    ...
}

이제 소비자 코드에서 다소 신비 롭고 모호한 생성자가 다음과 같이 호출됩니다.

$a = new Color(0,0,0);
$b = new Color('#000000');

대신 다음과 같이 더 읽기 쉬운 시맨틱 소비자 코드를 가질 수 있습니다.

$a = Color::fromRGB(0,0,0);
$b = Color::fromHex('#000000');

이것은 아마도 소비자 코드를 읽는 사람에게 더 합리적 일 것입니다. 모호한 생성자를 작동시키는 데 필요한 논리를 제거하고, 보너스 (PHPStorm과 같은 IDE를 사용하는 경우) 모든 검사를 통과 할 수 있습니다. 문서 생성기를 실행하는 경우 구두 설명으로 함께 모여있는 대신 모든 옵션이 개별적으로 문서화되도록합니다.

생성자를 선언했습니다 protected - 이것은 개인적인 취향이지만, 여러 정적 공장 메드를 가지고 있다면 때로는 보는 대신 소비자 코드에 지속적으로 사용되는 것을 선호합니다. Color::fromRGB(...) 그리고 다른 시간 new Color(...).

나는 그것이 사용하는 것이 더 낫다고 생각합니다 @method 오버로드 메소드를 선언하는 클래스/인터페이스에 대한 주석. 이 질문은 나에게도 흥미 롭습니다.

 /**
  * @method void setValue(int $value)
  * @method void setValue(string $value)
  * @method void setValue(string $value, int $startFrom)
  */
 class Example
 {
     public function setValue($arg1, $arg2)
     {
        // ...
     }
 }

보다 http://phpdoc.org/docs/latest/references/phpdoc/tags/method.html

나는 PHPDOC로 이것을하는 우아한 방법이 없다는 것을 알고 있습니다. PHPDOC 주석/API 형식은 A를 기반으로합니다. Javadoc 체재. Javadoc에는 Java에서는 변수의 인수를 원한다면 각 변형에 대한 메소드 프로토 타입을 다시 설명 할 수 있기 때문에이를 지원하는 기능 세트가 없습니다.

public double foo() {
}

public double foo(double my_param) {        
}

그래서 내 성능 선호는 다음과 같은 일을하는 것입니다.

/**
 * My General description
 * 
 * Here explain what each argument combination can do
 * @param mixed $arg1 can be array, string, hex as string, or int 
 * @param int $arg2 if arg1 is int, then this is etc, otherwise optional 
 * @param int $arg3 if ar1 is int, then this is etc, otherwise optional
 */

그러나 이것은 다양한 자동 문서화 도구에서는 좋지 않을 수 있습니다.

이를 달성하는 Hoyle 방법에 따르면 PHPDOC 사이트.

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