?
本文檔使用
php中文網(wǎng)手冊(cè) 發(fā)布
PHPDoc 是注釋 PHP 代碼的非正式標(biāo)準(zhǔn)。它有許多不同的標(biāo)記可以使用。完整的標(biāo)記列表和范例可以查看 PHPDoc 指南。
如下是撰寫(xiě)類(lèi)方法時(shí)的一種寫(xiě)法：
<?php
/**
* @author A Name <a.name@example.com>
* @link http://www.phpdoc.org/docs/latest/index.html
*/
class DateTimeHelper {
/**
* @param mixed $anything Anything that we can convert to a \DateTime object
*
* @throws \InvalidArgumentException
*
* @return \DateTime
*/
public function dateTimeFromAnything($anything){
$type = gettype($anything);
switch ($type) {
// Some code that tries to return a \DateTime object
}
throw new \InvalidArgumentException(
"Failed Converting param of type '{$type}' to DateTime object" );
}
/**
* @param mixed $date Anything that we can convert to a \DateTime object
*
* @return void
*/
public function printISO8601Date($date){
echo $this->dateTimeFromAnything($date)->format('c');
}
/**
* @param mixed $date Anything that we can convert to a \DateTime object
*/
public function printRFC2822Date($date){
echo $this->dateTimeFromAnything($date)->format('r');
}
}這個(gè)類(lèi)使用了 @author 和 @link 標(biāo)記來(lái)為整個(gè)類(lèi)添加說(shuō)明。 @author 標(biāo)記是用來(lái)說(shuō)明代碼的作者，在多位開(kāi)發(fā)者的情況下，可以同時(shí)列出好幾位作者。其次 @link 標(biāo)記用來(lái)提供網(wǎng)站鏈接，進(jìn)一步說(shuō)明代碼和網(wǎng)站之間的關(guān)系。
在這個(gè)類(lèi)中，第一個(gè)方法的 @param 標(biāo)記，說(shuō)明類(lèi)型、名字和傳入方法的參數(shù)。此外，@return 和 @throws 標(biāo)記分別說(shuō)明返回類(lèi)型以及可能拋出的異常。
第二和第三個(gè)方法非常類(lèi)似，和第一個(gè)方法一樣使用了一個(gè) @param 標(biāo)記。第二、和第三個(gè)方法之間關(guān)鍵差別在注釋區(qū)塊使用／排除 @return 標(biāo)記。@return void 標(biāo)記明確告訴我們沒(méi)有返回值，而過(guò)去省略 @return void 聲明也具有相同效果（沒(méi)有返回任何值）。