From 1dc778fe07a032727bf76043eb7ae23953d10181 Mon Sep 17 00:00:00 2001
From: Gareth Evans <garoevans@gmail.com>
Date: Tue, 1 Jul 2014 13:32:54 +0100
Subject: [PATCH] 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 %}
 <?php
 /**
  * @author A Name <a.name@example.com>
  * @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