From b717500558d9433b10a40e6a91c67c811001e5cb Mon Sep 17 00:00:00 2001 From: Gareth Evans Date: Fri, 20 Jun 2014 21:29:47 +0100 Subject: [PATCH 1/3] Add a PHPDoc post --- _posts/15-01-01-PHPDoc.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 _posts/15-01-01-PHPDoc.md diff --git a/_posts/15-01-01-PHPDoc.md b/_posts/15-01-01-PHPDoc.md new file mode 100644 index 0000000..6b10b60 --- /dev/null +++ b/_posts/15-01-01-PHPDoc.md @@ -0,0 +1,36 @@ +--- +anchor: phpdoc +--- + +# PHPDoc {#phpdoc} + +PHPDoc is an informal standard for commenting PHP code. There are a *lot* of different [tags](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) available. The full list of tags and examples can be found at the [PHPDoc manual](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html). + +Below is an example of how you might comment a class and a method; + +{% highlight php %} + + * @link http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.link.pkg.html + * @package demo + */ +class DateTimeHelper +{ + /** + * @param mixed $anything + * + * @return \DateTime + * @throws \InvalidArgumentException + */ + public static function dateTimeFromAnything($anything) { + $type = gettype($anything); + + switch ($type) { + case "object": + if ($anything instanceof \DateTime) { + return $anything; + } + break; +... +{% endhighlight %} From c3c45a89698e817c062e9cbbe1ca2a42401753d9 Mon Sep 17 00:00:00 2001 From: Gareth Evans Date: Mon, 23 Jun 2014 09:26:08 +0100 Subject: [PATCH 2/3] Updated the URLs to new documentation after some feedback --- _posts/15-01-01-PHPDoc.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_posts/15-01-01-PHPDoc.md b/_posts/15-01-01-PHPDoc.md index 6b10b60..1645f07 100644 --- a/_posts/15-01-01-PHPDoc.md +++ b/_posts/15-01-01-PHPDoc.md @@ -4,7 +4,7 @@ anchor: phpdoc # PHPDoc {#phpdoc} -PHPDoc is an informal standard for commenting PHP code. There are a *lot* of different [tags](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html) available. The full list of tags and examples can be found at the [PHPDoc manual](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.pkg.html). +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 comment a class and a method; @@ -12,7 +12,7 @@ Below is an example of how you might comment a class and a method; - * @link http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.link.pkg.html + * @link http://www.phpdoc.org/docs/latest/index.html * @package demo */ class DateTimeHelper From 1dc778fe07a032727bf76043eb7ae23953d10181 Mon Sep 17 00:00:00 2001 From: Gareth Evans Date: Tue, 1 Jul 2014 13:32:54 +0100 Subject: [PATCH 3/3] Expand documentation and explain (and it's exclusion) --- _posts/15-01-01-PHPDoc.md | 47 ++++++++++++++++++++++++++++++--------- 1 file changed, 37 insertions(+), 10 deletions(-) diff --git a/_posts/15-01-01-PHPDoc.md b/_posts/15-01-01-PHPDoc.md index 1645f07..f0fec15 100644 --- a/_posts/15-01-01-PHPDoc.md +++ b/_posts/15-01-01-PHPDoc.md @@ -6,31 +6,58 @@ anchor: 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 comment a class and a method; +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 demo + * @package helper */ class DateTimeHelper { /** - * @param mixed $anything + * @param mixed $anything Anything that we can convert to a \DateTime object * * @return \DateTime * @throws \InvalidArgumentException */ - public static function dateTimeFromAnything($anything) { + public function dateTimeFromAnything($anything) + { $type = gettype($anything); switch ($type) { - case "object": - if ($anything instanceof \DateTime) { - return $anything; - } - break; -... + // 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. \ No newline at end of file