Yüklenmiş yöntemleri ile PHPDoc nasıl kullanılır?

4 Cevap php

Diyelim ki Color adında bir PHP sınıfı var diyelim, bu yapıcı çeşitli params kabul var.

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

Nasıl yapıcı ve bu gibi diğer yöntemler için API belgelerine oluşturmak için PHPDoc kullanmalıyım?

Yüklenmiş yöntemleri ile PHPDoc nasıl kullanılır?

class Color {

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

}

4 Cevap

Eğer izin Çünkü değişken uzunluk argümanları ben bu yapacağını iki yolu vardır.

Ben sadece izin verilen argümanlar parametrelerdir listelemek.

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

Yoksa sadece bazı örnekler ile bir açıklama sağlayacaktır.

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

Başka bir alternatif, tek örneklerden birden fazla bağımsız değişken olması nedeniyle, sadece son 2 isteğe bağlı hale yöntem imzası bağımsız değişkenleri tanımlamak olacaktır. Bu gibi:

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

Sadece benim bakış açısı, ancak ilk etapta birden Kurucular olmamalıdır - Sizin yapıcı gerçekten özellikle bir temsili gibi hafif bir şey için iyi bir fikir değil, if / else-merdivenler, tam olacak renk.

Ben kuvvetle yerine böyle bir şey denemek teşvik:

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) { ... }

    ...
}

Şimdi, tüketici kod yerine biraz gizemli ve belirsiz kurucusuna bu gibi aramaları:

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

Bunun yerine, bu gibi daha okunaklı ve anlamsal tüketici kodu olabilir:

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

Bu muhtemelen tüketici kodu okuma birine, bu belirsiz yapıcı işi yapmak için gerekli mantığı ortadan kaldırır ve (böyle PhpStorm gibi bir IDE kullanarak eğer) bir bonus olarak tüm denetimler geçmek olabilir daha mantıklı. Eğer bir dokümantasyon jeneratör çalışan ediyorsanız, bu da bir sözlü açıklama kefeye ziyade, tüm seçenekleri tek tek belgelenmiş olmasını sağlar.

Bu kişisel bir tercihtir, ama birden çok statik fabrika yöntemleri var gidiyorum, ben yerine bazen görmekten daha tutarlı tüketici kodunda kullanılan, {görmeyi tercih - I protected kurucu ilan unutmayın [(1)]} ve diğer zamanlarda new Color(...).

Ben PHPDoc ile bunu yapmak için hiçbir zarif bir şekilde biliyorum. Phpdoc Yorum / API biçimlendirme Javadoc biçimine dayanmaktadır. Javadoc Eğer her varyasyon yöntemi prototip yeniden ilan bağımsız değişken bir dizi için bir yöntem istiyorsanız, çünkü java bu destek için ayarlanmış bir özelliği yoktur.

public double foo() {
}

public double foo(double my_param) {        
}

Yani, benim performans tercihi gibi bir şey yapmak için

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

ancak bu çeşitli oto-dokümantasyon araçları ile oynamak güzel olmayabilir.

Gerçekleştirmek için Hoyle yol göre bu phpDoc site bulunabilir.

Ben bu aşırı yükleme yöntemleri beyan, hangi sınıf / arabirimi için @method ek açıklama kullanmak daha iyi olduğunu düşünüyorum. Bu soru benim için de ilginç.

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

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

etiketler