Ben bir sınıf uzatmak eğer PHP belgeleyen, ben kopyalamak gerekir / yapıştır?

2 Cevap php

Ben bir yöntem ile bir PHP sınıfı var. Temel sınıf (daha bir prototip gibi, ama biz geriye doğru uyumlu olmak zorunda çünkü ben prototipler kullanarak değilim), ben yöntemi parametrelerini ve açıklamasını belgelemek.

Şimdi bu sınıfı genişletir. Bu yeni yöntem (uygulama) ben gerektiğini yeniden belge parametreleri ve açıklama, ben boş bırakmak gerekir, yoksa sadece belirli bir uygulama için geçerli alakalı notlar bırakmak gerekir?

Amacım PHPDoc tarafından üretilen okunabilir API docs var, ve kuralları takip etmektir.

2 Cevap

Zend Framework birkaç örnek baktığımızda, bu yorumlar çoğunlukla kopyalayıp yapıştırılan görünüyor - ve bu bazen farklı yorumlarına yol açar.

Ben alacağım ilk örnek olarak beyan edildiği, Zend_Http_Client_Adapter_Interface::connect olduğunu:

/**
 * Connect to the remote server
 *
 * @param string  $host
 * @param int     $port
 * @param boolean $secure
 */
public function connect($host, $port = 80, $secure = false);

Eğer bu arayüzü uygulayan bir sınıf bakmak ve eğer, gibi Zend_Http_Client_Adapter_Curl, görürsünüz:

/**
 * Initialize curl
 *
 * @param  string  $host
 * @param  int     $port
 * @param  boolean $secure
 * @return void
 * @throws Zend_Http_Client_Adapter_Exception if unable to connect
 */
public function connect($host, $port = 80, $secure = false)

Yani, kopyalayıp yapıştırın parametrelerin; ve uygulanmasında daha fazla bilgiler.


Another example would be Zend_Log_Writer_Abstract::_write :

/**
 * Write a message to the log.
 *
 * @param  array  $event  log data event
 * @return void
 */
abstract protected function _write($event);

Ve, bir çocuk sınıfta gibi Zend_Log_Writer_Db:

/**
 * Write a message to the log.
 *
 * @param  array  $event  event data
 * @return void
 */
protected function _write($event)

Burada, yine, kopyala-yapıştır; ve, bu çocuk sınıfta üst sınıf küçük bir değişiklik yeniden yaratılmış olmamıştır.


Now, what do I generally do ?

  • Ben genellikle geliştiricilerin yeterince sık yorum yazmayın düşünün
  • Ve genelde forget bunları güncelleştirmek için
  • Yani, onların hayatını kolaylaştırmak için deneyin ve yorumlarınızı yinelenen yok
  • Çocuk sınıfta açıklama üst sınıfında birinden farklı olmak zorunda sürece.

Yöntem, bir çocuğun sınıfta geçersiz alırsa belgelenmiştir yöntem bir üst sınıfta yöntemi yeniden tanımlanması yanı sıra ise phpDocumentor size göstermek için gidiyor. Yani, yöntemin bilgilendirme kısmı koymak tüm bilgi yanı sıra, aynı zamanda akım yöntemi ile ilişkili bir ebeveyn yöntemi ve / veya çocuk bir yöntem olduğunu göreceksiniz. Bu yöntemin bilgilendirme kısmı içinde something söylemek için yararına olduğu anlamına gelir.

Ne yapmak eğilimindedir yukarı ana yöntemin doğru anahtar jenerik dili float, ama ben hala geçerli çocuğun yöntemi yanı sıra bir torun yöntemi hakkında söyleyecek bir şey olacak. Ana yöntemi çocuk yöntemi ayırır ne olursa olsun, ve / veya aynı ebeveynden kendi yaşıtları olan diğer çocuk yöntemlerle bu çocuk yöntemi farklılaştıran ne olursa olsun, bu çocuk yöntem bilgilendirme kısmı tarafından gerekli bilgi.

Ben bir çocuğa bir ebeveynden / yapıştır şey kopyalamak için asla ... Ben onun yerine daha onun ebeveyn ve / veya kardeşleri ile ilgili olan çocuk kılan açıklamak için gidiyorum. Tipik ebeveyn-çocuk ilişkisi soyut uzak çocukların özelliklerini bilmek gerek bir yol olarak yapılır beri Ayrıca, ben, not ebeveynin bilgilendirme kısmı içeride çocuklar hakkında bir şey söylemek için deneyin.

etiketler