Move the code documenting chapter up and put PHPDoc in a sub-section

There are other documentation tools out there. At the least there should be the possibility to add these.

_posts/15-02-01-PHPDoc.md

@@ -0,0 +1,84 @@
+---
+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 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