Docs: update the style guide

contributing/styleguide.rst

@@ -247,6 +247,82 @@ Control Structures
         if ( $foo ) $bar += $baz;
         else $baz = 'bar';
 
+Docblocks
+=========
+
+We use phpDocumentor (phpdoc) to generate the API docs, for all of the source
+code inside the `system` folder.
+
+It wants to see a file summary docblock at the top of a PHP file,
+before any PHP statements, and then a docblock before each documentable
+component, namely any class/interface/trait, and all public and protected
+methods/functions/variables. The docblock for a method or function
+is expected to describe the parameters, return value, and any exceptions
+thrown.
+
+Deviations from the above are considered errors by phpdoc.
+
+An example::
+
+    <?php
+
+    /**
+     * CodeIgniter
+     *
+     * An open source application development framework for PHP
+     *
+     ...
+     *
+     * @package    CodeIgniter
+     * @author     CodeIgniter Dev Team
+     * @copyright  2014-2019 British Columbia Institute of Technology (https://bcit.ca/)
+     * @license    https://opensource.org/licenses/MIT	MIT License
+     * @link       https://codeigniter.com
+     * @since      Version 3.0.0
+     * @filesource
+     */
+    namespace CodeIgniter\Fruit;
+    use CodeIgniter\Config\BaseConfig;
+
+    /**
+     * Base class for entities in the CodeIgniter\Fruit module.
+     *
+     * @property $group
+     * @property $name
+     * @property $description
+     *
+     * @package CodeIgniter\Fruit
+     */
+    abstract class BaseFruit
+    {
+
+            /**
+             * The group a fruit belongs to.
+             *
+             * @var string
+             */
+            protected $group;
+
+            /**
+             * Fruit constructor.
+             *
+             * @param BaseConfig       $config
+             */
+            public function __construct(BaseConfig $Config)
+            {
+                    $this->group   = 'Unknown';
+            }
+
+            //--------------------------------------------------------------------
+
+            /**
+             * Model a fruit ripening over time.
+             * 
+             * @param	array	$params
+             */
+            abstract public function ripen(array $params);
+    }
+
 Other
 =====
 

phpdoc.dist.xml

@@ -15,7 +15,7 @@
     </files>
 
     <logging>
-        <level>warn</level>
+        <level>err</level>
         <paths>
             <default>api/log/{DATE}.log</default>
             <errors>api/{DATE}.errors.log</errors>