Improve class docs

Also add some ToDos to inline docs

content-sample/index.md

@@ -303,7 +303,9 @@ particularly the [plugin upgrade section][PluginUpgrade].
   down to the massive performance impact, but leads to the removal of the
   generation of auto-generated excerpts.
   TODO: describe how to force enable/disable `PicoExcerpt` and `PicoParsePagesContent`
+  TODO: describe how to replace `PicoExcerpt`
 * TODO: Removing various empty `index.html` files; check accessibility!
+* TODO: Describe new features that are important for users... e.g. `%meta.*%`
 
 ## Documentation
 

lib/Pico.php

@@ -844,6 +844,7 @@ class Pico
      * Reads the data of all pages known to Pico
      *
      * The page data will be an array containing the following values:
+     * <pre>
      * +----------------+------------------------------------------+
      * | Array key      | Description                              |
      * +----------------+------------------------------------------+
@@ -858,6 +859,7 @@ class Pico
      * | raw_content    | raw, not yet parsed contents of the page |
      * | meta           | parsed meta data of the page)            |
      * +----------------+------------------------------------------+
+     * </pre>
      *
      * @see    Pico::sortPages()
      * @see    Pico::getPages()

plugins/00-PicoDeprecated.php

@@ -11,6 +11,7 @@
  * can disable this plugin by calling {@link PicoDeprecated::setEnabled()}.
  *
  * The following deprecated events are triggered by this plugin:
+ * <pre>
  * +---------------------+-----------------------------------------------------------+
  * | Event               | ... triggers the deprecated event                         |
  * +---------------------+-----------------------------------------------------------+
@@ -32,6 +33,7 @@
  * | onPageRendering     | before_render($twigVariables, $twig, $templateName)       |
  * | onPageRendered      | after_render($output)                                     |
  * +---------------------+-----------------------------------------------------------+
+ * </pre>
  *
  * Since Pico 1.0 the config is stored in {@path "config/config.php"}. This
  * plugin tries to read {@path "config.php"} in Picos root dir and overwrites

plugins/DummyPlugin.php

@@ -227,21 +227,26 @@ class DummyPlugin extends AbstractPicoPlugin
     /**
      * Triggered when Pico reads a single page from the list of all known pages
      *
-     * @see    DummyPlugin::onPagesLoaded()
-     * @param array &$pageData {
-     *     data of the loaded page
+     * The $pageData variable consits of the following values:
+     * <pre>
+     * +-----------------+--------+------------------------------------------+
+     * | Array key       | Type   | Description                              |
+     * +-----------------+--------+------------------------------------------+
+     * | $id             | string | relative path to the content file        |
+     * | $url            | string | URL to the page                          |
+     * | $title          | string | title of the page (YAML header)          |
+     * | $description    | string | description of the page (YAML header)    |
+     * | $author         | string | author of the page (YAML header)         |
+     * | $time           | string | timestamp derived from the Date header   |
+     * | $date           | string | date of the page (YAML header)           |
+     * | $date_formatted | string | formatted date of the page               |
+     * | $raw_content    | string | raw, not yet parsed contents of the page |
+     * | $meta           | string | parsed meta data of the page             |
+     * +-----------------+--------+------------------------------------------+
+     * </pre>
      *
-     *     @var string $id             relative path to the content file
-     *     @var string $url            URL to the page
-     *     @var string $title          title of the page (YAML header)
-     *     @var string $description    description of the page (YAML header)
-     *     @var string $author         author of the page (YAML header)
-     *     @var string $time           timestamp derived from the Date header
-     *     @var string $date           date of the page (YAML header)
-     *     @var string $date_formatted formatted date of the page
-     *     @var string $raw_content    raw, not yet parsed contents of the page
-     *     @var string $meta           parsed meta data of the page
-     * }
+     * @see    DummyPlugin::onPagesLoaded()
+     * @param  array &$pageData data of the loaded page
      * @return void
      */
     public function onSinglePageLoaded(&$pageData)