mirror of
https://github.com/codeguy/php-the-right-way.git
synced 2025-08-12 16:54:00 +02:00
63
_posts/15-01-01-PHPDoc.md
Normal file
63
_posts/15-01-01-PHPDoc.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
anchor: phpdoc
|
||||
---
|
||||
|
||||
# PHPDoc {#phpdoc}
|
||||
|
||||
PHPDoc is an informal standard for commenting PHP code. There are a *lot* of different [tags](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/index.html) available. The full list of tags and examples can be found at the [PHPDoc manual](http://www.phpdoc.org/docs/latest/index.html).
|
||||
|
||||
Below is an example of how you might document a class with a few methods;
|
||||
|
||||
{% highlight php %}
|
||||
<?php
|
||||
/**
|
||||
* @author A Name <a.name@example.com>
|
||||
* @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](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/author.html) tag, this tag is used to document the author of the code and can be repeated for documenting several authors. Secondly is the [@link](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/link.html) tag, used to link to a website indicating a relationship between the website and the code. Thirdly it has the [@pacakge](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/package.html) tag, used to categorize the code.
|
||||
|
||||
Inside the class, the first method has an [@param](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/param.html) tag documenting the type, name and description of the parameter being passed to the method. Additionally it has the [@return](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/return.html) and [@throws](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/throws.html) 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](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/param.html) 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](http://www.phpdoc.org/docs/latest/references/phpdoc/tags/return.html) 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.
|
Reference in New Issue
Block a user