| isChild | title | anchor |
|---|---|---|
true |
PHPDoc |
phpdoc |
PHPDoc is an informal standard for commenting PHP code. There are a lot of different [tags] available. The full list of tags and examples can be found at the [PHPDoc manual].
Below is an example of how you might document a class with a few methods;
{% highlight php %}
* @link http://www.phpdoc.org/docs/latest/index.html * @package helper */ class DateTimeHelper { /** * @param mixed $anything Anything that we can convert to a \DateTime object * * @return \DateTime * @throws \InvalidArgumentException */ 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'); } } {% endhighlight %} The documentation for the class as a whole firstly has the [@author] tag, this tag is used to document the author of the code and can be repeated for documenting several authors. Secondly is the [@link] tag, used to link to a website indicating a relationship between the website and the code. Thirdly it has the [@package] tag, used to categorize the code. Inside the class, the first method has an [@param] tag documenting the type, name and description of the parameter being passed to the method. Additionally it has the [@return] and [@throws] tags for documenting the return type, and any exceptions that could be throw respectively. The second and third methods are very similar and have a single [@param] tag as did the first method. The import difference between the second and third method is doc block is the inclusion/exclusion of the [@return] tag. `@return void` explicitly informs us that there is no return, historically omitting the `@return void` statement also results in the same (no return) action. [tags]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/index.html [PHPDoc manual]: http://www.phpdoc.org/docs/latest/index.html [@author]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/author.html [@link]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/link.html [@package]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html [@param]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/param.html [@return]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/return.html [@throws]: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/throws.html