mirror of
https://github.com/codeguy/php-the-right-way.git
synced 2025-08-11 00:03:58 +02:00
80 lines
2.8 KiB
Markdown
80 lines
2.8 KiB
Markdown
---
|
|
isChild: true
|
|
title: PHPDoc
|
|
anchor: phpdoc
|
|
---
|
|
|
|
## PHPDoc {#phpdoc_title}
|
|
|
|
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 %}
|
|
<?php
|
|
/**
|
|
* @author A Name <a.name@example.com>
|
|
* @link https://docs.phpdoc.org/
|
|
*/
|
|
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');
|
|
}
|
|
}
|
|
{% endhighlight %}
|
|
|
|
The documentation for the class as a whole has the [@author] tag and a [@link] tag. The [@author] tag is used to
|
|
document the author of the code and can be repeated for documenting several authors. The [@link] tag is used to link to a website indicating a relationship between the website and the code.
|
|
|
|
Inside the class, the first method has a [@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 thrown respectively.
|
|
|
|
The second and third methods are very similar and have a single [@param] tag as did the first method. The important
|
|
difference between the second and third methods' 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]: https://docs.phpdoc.org/guide/references/phpdoc/tags/
|
|
[PHPDoc manual]: https://docs.phpdoc.org/
|
|
[@author]: https://docs.phpdoc.org/guide/references/phpdoc/tags/author.html
|
|
[@link]: https://docs.phpdoc.org/guide/references/phpdoc/tags/link.html
|
|
[@param]: https://docs.phpdoc.org/guide/references/phpdoc/tags/param.html
|
|
[@return]: https://docs.phpdoc.org/guide/references/phpdoc/tags/return.html
|
|
[@throws]: https://docs.phpdoc.org/guide/references/phpdoc/tags/throws.html
|