Add license/copyright file header; improve phpDoc class docs

composer.json

@@ -13,8 +13,11 @@
         },
         {
             "name": "The Pico Community",
-            "homepage": "https://github.com/picocms/Pico/graphs/contributors",
-            "role": "Contributors"
+            "homepage": "http://picocms.org/"
+        },
+        {
+            "name": "Contributors",
+            "homepage": "https://github.com/picocms/Pico/graphs/contributors"
         }
     ],
     "support": {

lib/AbstractPicoPlugin.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * This file is part of Pico. It's copyrighted by the contributors recorded
+ * in the version control history of the file, available from the following
+ * original location:
+ *
+ * <https://github.com/picocms/Pico/blob/master/lib/AbstractPicoPlugin.php>
+ *
+ * SPDX-License-Identifier: MIT
+ * License-Filename: LICENSE
+ */
 
 /**
  * Abstract class to extend from when implementing a Pico plugin
@@ -24,11 +34,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
     private $pico;
 
     /**
-     * Boolean indicating if this plugin is enabled (true) or disabled (false)
+     * Boolean indicating if this plugin is enabled (TRUE) or disabled (FALSE)
      *
      * @see PicoPluginInterface::isEnabled()
      * @see PicoPluginInterface::setEnabled()
-     * @var boolean
+     * @var bool
      */
     protected $enabled = true;
 
@@ -36,7 +46,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * Boolean indicating if this plugin was ever enabled/disabled manually
      *
      * @see PicoPluginInterface::isStatusChanged()
-     * @var boolean
+     * @var bool
      */
     protected $statusChanged = false;
 
@@ -44,7 +54,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * Boolean indicating whether this plugin matches Pico's API version
      *
      * @see AbstractPicoPlugin::checkCompatibility()
-     * @var boolean|null
+     * @var bool|null
      */
     protected $nativePlugin;
 
@@ -155,11 +165,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * @param string $configName optional name of a config variable
      * @param mixed  $default    optional default value to return when the
      *     named config variable doesn't exist
-     * @return mixed              if no name of a config variable has been
-     *     supplied, the plugin's config array is returned; otherwise it
-     *     returns either the value of the named config variable, or, if the
-     *     named config variable doesn't exist, the provided default value
-     *     or NULL
+     *
+     * @return mixed if no name of a config variable has been supplied, the
+     *     plugin's config array is returned; otherwise it returns either the
+     *     value of the named config variable, or, if the named config variable
+     *     doesn't exist, the provided default value or NULL
      */
     public function getPluginConfig($configName = null, $default = null)
     {
@@ -176,8 +186,10 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * Passes all not satisfiable method calls to Pico
      *
      * @see Pico
+     *
      * @param string $methodName name of the method to call
      * @param array  $params     parameters to pass
+     *
      * @return mixed return value of the called method
      */
     public function __call($methodName, array $params)
@@ -196,8 +208,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * Enables all plugins which this plugin depends on
      *
      * @see PicoPluginInterface::getDependencies()
-     * @param  boolean $recursive enable required plugins automatically
+     *
+     * @param bool $recursive enable required plugins automatically
+     *
      * @return void
+     *
      * @throws RuntimeException thrown when a dependency fails
      */
     protected function checkDependencies($recursive)
@@ -245,8 +260,11 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * Disables all plugins which depend on this plugin
      *
      * @see PicoPluginInterface::getDependants()
-     * @param  boolean $recursive disabled dependant plugins automatically
+     *
+     * @param bool $recursive disabled dependant plugins automatically
+     *
      * @return void
+     *
      * @throws RuntimeException thrown when a dependency fails
      */
     protected function checkDependants($recursive)
@@ -308,8 +326,9 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
      * newer API versions, what defaults to "no" by default.
      *
      * @return void
-     * @throws RuntimeException thrown when the plugin's and Pico's API
-     *     aren't compatible
+     *
+     * @throws RuntimeException thrown when the plugin's and Pico's API aren't
+     *     compatible
      */
     protected function checkCompatibility()
     {

lib/Pico.php

@@ -1,4 +1,20 @@
 <?php
+/**
+ * This file is part of Pico. It's copyrighted by the contributors recorded
+ * in the version control history of the file, available from the following
+ * original location:
+ *
+ * <https://github.com/picocms/Pico/blob/master/lib/Pico.php>
+ *
+ * The file has been renamed in the past; the version control history of the
+ * original file applies accordingly, available from the following original
+ * location:
+ *
+ * <https://github.com/picocms/Pico/blob/adc356251ecd79689935ec1446c7c846db167d46/lib/pico.php>
+ *
+ * SPDX-License-Identifier: MIT
+ * License-Filename: LICENSE
+ */
 
 /**
  * Pico
@@ -116,7 +132,7 @@ class Pico
     /**
      * Boolean indicating whether Pico started processing yet
      *
-     * @var boolean
+     * @var bool
      */
     protected $locked = false;
 
@@ -180,7 +196,7 @@ class Pico
      * Boolean indicating whether Pico is serving a 404 page
      *
      * @see Pico::is404Content()
-     * @var boolean
+     * @var bool
      */
     protected $is404Content = false;
 
@@ -360,7 +376,8 @@ class Pico
      * the rendered contents.
      *
      * @return string rendered Pico contents
-     * @throws Exception thrown when a not recoverable error occurs
+     *
+     * @throws Exception thrown when a irrecoverable error occurs
      */
     public function run()
     {
@@ -473,7 +490,9 @@ class Pico
      * @see Pico::loadPlugin()
      * @see Pico::getPlugin()
      * @see Pico::getPlugins()
+     *
      * @return void
+     *
      * @throws RuntimeException thrown when a plugin couldn't be loaded
      */
     protected function loadPlugins()
@@ -494,7 +513,9 @@ class Pico
      *
      * @see Pico::loadPlugins()
      * @see Pico::loadLocalPlugins()
+     *
      * @param string[] $pluginBlacklist class names of plugins not to load
+     *
      * @return string[] installer names of the loaded plugins
      */
     protected function loadComposerPlugins(array $pluginBlacklist = array())
@@ -560,8 +581,11 @@ class Pico
      *
      * @see Pico::loadPlugins()
      * @see Pico::loadComposerPlugins()
+     *
      * @param string[] $pluginBlacklist class names of plugins not to load
+     *
      * @return void
+     *
      * @throws RuntimeException thrown when a plugin couldn't be loaded
      */
     protected function loadLocalPlugins(array $pluginBlacklist = array())
@@ -649,11 +673,13 @@ class Pico
      * @see Pico::loadPlugins()
      * @see Pico::getPlugin()
      * @see Pico::getPlugins()
+     *
      * @param PicoPluginInterface|string $plugin either the class name of a
      *     plugin to instantiate or a plugin instance
+     *
      * @return PicoPluginInterface instance of the loaded plugin
-     * @throws RuntimeException                   thrown when a plugin couldn't
-     *     be loaded
+     *
+     * @throws RuntimeException thrown when a plugin couldn't be loaded
      */
     public function loadPlugin($plugin)
     {
@@ -714,6 +740,7 @@ class Pico
      *     Marc J. Schmidt's Topological Sort / Dependency resolver in PHP
      * @see https://github.com/marcj/topsort.php/blob/1.1.0/src/Implementations/ArraySort.php
      *     \MJS\TopSort\Implementations\ArraySort class
+     *
      * @return void
      */
     protected function sortPlugins()
@@ -775,8 +802,11 @@ class Pico
      *
      * @see Pico::loadPlugins()
      * @see Pico::getPlugins()
+     *
      * @param string $pluginName name of the plugin
+     *
      * @return object instance of the plugin
+     *
      * @throws RuntimeException thrown when the plugin wasn't found
      */
     public function getPlugin($pluginName)
@@ -793,6 +823,7 @@ class Pico
      *
      * @see Pico::loadPlugins()
      * @see Pico::getPlugin()
+     *
      * @return object[]|null
      */
     public function getPlugins()
@@ -813,6 +844,7 @@ class Pico
      *
      * @see Pico::setConfig()
      * @see Pico::getConfig()
+     *
      * @return void
      */
     protected function loadConfig()
@@ -923,8 +955,11 @@ class Pico
      *
      * @see Pico::loadConfig()
      * @see Pico::getConfig()
+     *
      * @param array $config array with config variables
+     *
      * @return void
+     *
      * @throws LogicException thrown if Pico already started processing
      */
     public function setConfig(array $config)
@@ -942,13 +977,15 @@ class Pico
      *
      * @see Pico::setConfig()
      * @see Pico::loadConfig()
+     *
      * @param string $configName optional name of a config variable
      * @param mixed  $default    optional default value to return when the
      *     named config variable doesn't exist
-     * @return mixed              if no name of a config variable has been
-     *     supplied, the config array is returned; otherwise it returns either
-     *     the value of the named config variable, or, if the named config
-     *     variable doesn't exist, the provided default value or NULL
+     *
+     * @return mixed if no name of a config variable has been supplied, the
+     *     config array is returned; otherwise it returns either the value of
+     *     the named config variable, or, if the named config variable doesn't
+     *     exist, the provided default value or NULL
      */
     public function getConfig($configName = null, $default = null)
     {
@@ -995,6 +1032,7 @@ class Pico
      * `/pico/?someBooleanParam=` or `/pico/?index&someBooleanParam` instead.
      *
      * @see Pico::getRequestUrl()
+     *
      * @return void
      */
     protected function evaluateRequestUrl()
@@ -1031,6 +1069,7 @@ class Pico
      * Returns the URL where a user requested the page
      *
      * @see Pico::evaluateRequestUrl()
+     *
      * @return string|null request URL
      */
     public function getRequestUrl()
@@ -1049,7 +1088,9 @@ class Pico
      * with Pico!
      *
      * @see Pico::getRequestFile()
+     *
      * @param string $requestUrl path name (likely from a URL) to resolve
+     *
      * @return string path to the resolved content file
      */
     public function resolveFilePath($requestUrl)
@@ -1100,7 +1141,8 @@ class Pico
      * Returns the absolute path to the content file to serve
      *
      * @see Pico::resolveFilePath()
-     * @return string|null file path
+     *
+     * @return string|null file pat
      */
     public function getRequestFile()
     {
@@ -1111,7 +1153,9 @@ class Pico
      * Returns the raw contents of a file
      *
      * @see Pico::getRawContent()
+     *
      * @param string $file file path
+     *
      * @return string raw contents of the file
      */
     public function loadFileContent($file)
@@ -1126,7 +1170,9 @@ class Pico
      * If no suitable `404.md` is found, fallback to a built-in error message.
      *
      * @see Pico::getRawContent()
+     *
      * @param string $file path to requested (but not existing) file
+     *
      * @return string raw contents of the 404 file
      */
     public function load404Content($file)
@@ -1167,6 +1213,7 @@ class Pico
      *
      * @see Pico::loadFileContent()
      * @see Pico::load404Content()
+     *
      * @return string|null raw contents
      */
     public function getRawContent()
@@ -1178,7 +1225,8 @@ class Pico
      * Returns TRUE when Pico is serving a 404 page
      *
      * @see Pico::load404Content()
-     * @return boolean TRUE if Pico is serving a 404 page, FALSE otherwise
+     *
+     * @return bool TRUE if Pico is serving a 404 page, FALSE otherwise
      */
     public function is404Content()
     {
@@ -1191,8 +1239,8 @@ class Pico
      * This method triggers the `onMetaHeaders` event when the known meta
      * headers weren't assembled yet.
      *
-     * @return string[] known meta headers; the array value specifies the
-     *     YAML key to search for, the array key is later used to access the
+     * @return string[] known meta headers; the array key specifies the YAML
+     *     key to search for, the array value is later used to access the
      *     found value
      */
     public function getMetaHeaders()
@@ -1242,9 +1290,12 @@ class Pico
      * for users and pure (!) theme developers ONLY.
      *
      * @see Pico::getFileMeta()
+     *
      * @param string   $rawContent the raw file contents
      * @param string[] $headers    known meta headers
+     *
      * @return array parsed meta data
+     *
      * @throws \Symfony\Component\Yaml\Exception\ParseException thrown when the
      *     meta data is invalid
      */
@@ -1306,6 +1357,7 @@ class Pico
      * Returns the parsed meta data of the requested page
      *
      * @see Pico::parseFileMeta()
+     *
      * @return array|null parsed meta data
      */
     public function getFileMeta()
@@ -1346,8 +1398,10 @@ class Pico
      * @see Pico::substituteFileContent()
      * @see Pico::parseFileContent()
      * @see Pico::getFileContent()
+     *
      * @param string $rawContent raw contents of a page
      * @param array  $meta       meta data to use for %meta.*% replacement
+     *
      * @return string prepared Markdown contents
      */
     public function prepareFileContent($rawContent, array $meta)
@@ -1368,6 +1422,7 @@ class Pico
      *
      * @param string $markdown Markdown contents of a page
      * @param array  $meta     meta data to use for %meta.*% replacement
+     *
      * @return string substituted Markdown contents
      */
     public function substituteFileContent($markdown, array $meta = array())
@@ -1412,7 +1467,9 @@ class Pico
      * @see Pico::prepareFileContent()
      * @see Pico::substituteFileContent()
      * @see Pico::getFileContent()
+     *
      * @param string $markdown Markdown contents of a page
+     *
      * @return string parsed contents (HTML)
      */
     public function parseFileContent($markdown)
@@ -1426,6 +1483,7 @@ class Pico
      * @see Pico::prepareFileContent()
      * @see Pico::substituteFileContent()
      * @see Pico::parseFileContent()
+     *
      * @return string|null parsed contents
      */
     public function getFileContent()
@@ -1448,19 +1506,20 @@ class Pico
      * | time           | string  | timestamp derived from the Date header     |
      * | date           | string  | date of the page (YAML header)             |
      * | date_formatted | string  | formatted date of the page                 |
-     * | hidden         | boolean | this page shouldn't be visible to the user |
+     * | hidden         | bool    | this page shouldn't be visible to the user |
      * | raw_content    | string  | raw, not yet parsed contents of the page   |
      * | meta           | string  | parsed meta data of the page               |
      * | previous_page  | &array  | reference to the previous page             |
      * | next_page      | &array  | reference to the next page                 |
      *
      * Please note that the `previous_page` and `next_page` keys won't be
-     * available until the `onCurrentPageDiscovered` event
-     * ({@see Pico::discoverPageSiblings()}) was triggered.
+     * available until the `onCurrentPageDiscovered` event was triggered
+     * ({@see Pico::discoverPageSiblings()}).
      *
      * @see Pico::sortPages()
      * @see Pico::discoverPageSiblings()
      * @see Pico::getPages()
+     *
      * @return void
      */
     protected function readPages()
@@ -1547,6 +1606,7 @@ class Pico
      *
      * @see Pico::readPages()
      * @see Pico::getPages()
+     *
      * @return void
      */
     protected function sortPages()
@@ -1627,6 +1687,7 @@ class Pico
      *
      * @see Pico::readPages()
      * @see Pico::getPages()
+     *
      * @return void
      */
     protected function discoverPageSiblings()
@@ -1662,6 +1723,7 @@ class Pico
      * Returns the list of known pages
      *
      * @see Pico::readPages()
+     *
      * @return array[]|null the data of all pages
      */
     public function getPages()
@@ -1676,6 +1738,7 @@ class Pico
      * @see Pico::getCurrentPage()
      * @see Pico::getPreviousPage()
      * @see Pico::getNextPage()
+     *
      * @return void
      */
     protected function discoverCurrentPage()
@@ -1692,6 +1755,7 @@ class Pico
      * Returns the data of the requested page
      *
      * @see Pico::discoverCurrentPage()
+     *
      * @return array|null page data
      */
     public function getCurrentPage()
@@ -1703,6 +1767,7 @@ class Pico
      * Returns the data of the previous page relative to the page being served
      *
      * @see Pico::discoverCurrentPage()
+     *
      * @return array|null page data
      */
     public function getPreviousPage()
@@ -1714,6 +1779,7 @@ class Pico
      * Returns the data of the next page relative to the page being served
      *
      * @see Pico::discoverCurrentPage()
+     *
      * @return array|null page data
      */
     public function getNextPage()
@@ -1732,6 +1798,7 @@ class Pico
      * @see Pico::getTwig()
      * @see http://twig.sensiolabs.org/ Twig website
      * @see https://github.com/twigphp/Twig Twig on GitHub
+     *
      * @return Twig_Environment|null Twig template engine
      */
     public function getTwig()
@@ -1857,7 +1924,7 @@ class Pico
     /**
      * Returns TRUE if URL rewriting is enabled
      *
-     * @return boolean TRUE if URL rewriting is enabled, FALSE otherwise
+     * @return bool TRUE if URL rewriting is enabled, FALSE otherwise
      */
     public function isUrlRewritingEnabled()
     {
@@ -1886,8 +1953,9 @@ class Pico
      * @param string       $page      identifier of the page to link to
      * @param array|string $queryData either an array containing properties to
      *     create a URL-encoded query string from, or a already encoded string
-     * @param  boolean      $dropIndex when the last path component is "index",
+     * @param bool         $dropIndex when the last path component is "index",
      *     then passing TRUE (default) leads to removing this path component
+     *
      * @return string URL
      */
     public function getPageUrl($page, $queryData = null, $dropIndex = true)
@@ -1929,6 +1997,7 @@ class Pico
      * Returns the page ID of a given content file
      *
      * @param string $path path to the content file
+     *
      * @return string|null either the corresponding page ID or NULL
      */
     public function getPageId($path)
@@ -1992,16 +2061,18 @@ class Pico
      * used in Twig templates by calling the `url_param` function.
      *
      * @see Pico::filterVariable()
+     *
      * @param string                    $name    name of the URL GET parameter
      *     to filter
      * @param int|string                $filter  the filter to apply
      * @param mixed|array               $options either a associative options
      *     array to be used by the filter or a scalar default value
-     * @param  int|string|int[]|string[] $flags   flags and flag strings to
-     *     be used by the filter
-     * @return mixed                              either the filtered data,
-     *     FALSE if the filter fails, or NULL if the URL GET parameter doesn't
-     *     exist and no default value is given
+     * @param int|string|int[]|string[] $flags   flags and flag strings to be
+     *     used by the filter
+     *
+     * @return mixed either the filtered data, FALSE if the filter fails, or
+     *     NULL if the URL GET parameter doesn't exist and no default value is
+     *     given
      */
     public function getUrlParameter($name, $filter = '', $options = null, $flags = null)
     {
@@ -2017,16 +2088,18 @@ class Pico
      * used in Twig templates by calling the `form_param` function.
      *
      * @see Pico::filterVariable()
+     *
      * @param string                    $name    name of the HTTP POST
      *     parameter to filter
      * @param int|string                $filter  the filter to apply
      * @param mixed|array               $options either a associative options
      *     array to be used by the filter or a scalar default value
-     * @param  int|string|int[]|string[] $flags   flags and flag strings to
-     *     be used by the filter
-     * @return mixed                              either the filtered data,
-     *     FALSE if the filter fails, or NULL if the HTTP POST parameter
-     *     doesn't exist and no default value is given
+     * @param int|string|int[]|string[] $flags   flags and flag strings to be
+     *     used by the filter
+     *
+     * @return mixed either the filtered data, FALSE if the filter fails, or
+     *     NULL if the HTTP POST parameter doesn't exist and no default value
+     *     is given
      */
     public function getFormParameter($name, $filter = '', $options = null, $flags = null)
     {
@@ -2057,6 +2130,7 @@ class Pico
      *     Validate filters
      * @see https://secure.php.net/manual/en/filter.filters.sanitize.php
      *     Sanitize filters
+     *
      * @param mixed                     $variable value to filter
      * @param int|string                $filter   ID (int) or name (string) of
      *     the filter to apply; if omitted, the method will return FALSE
@@ -2069,12 +2143,12 @@ class Pico
      *     (the constant name is the result of "FILTER_FLAG_" and the given
      *     string in ASCII-only uppercase); you may also pass an array of flags
      *     and flag strings (optional)
-     * @return mixed                               with a validation filter,
-     *     the method either returns the validated value or, provided that the
-     *     value wasn't valid, the given default value or FALSE; with a
-     *     sanitization filter, the method returns the sanitized value; if no
-     *     value (i.e. NULL) was given, the method always returns either the
-     *     provided default value or NULL
+     *
+     * @return mixed with a validation filter, the method either returns the
+     *     validated value or, provided that the value wasn't valid, the given
+     *     default value or FALSE; with a sanitization filter, the method
+     *     returns the sanitized value; if no value (i.e. NULL) was given, the
+     *     method always returns either the provided default value or NULL
      */
     protected function filterVariable($variable, $filter = '', $options = null, $flags = null)
     {
@@ -2123,6 +2197,7 @@ class Pico
      *     sorted; use Pico::SORT_ASC for a alphabetical ascending order (this
      *     is the default behaviour), Pico::SORT_DESC for a descending order
      *     or Pico::SORT_NONE to leave the result unsorted
+     *
      * @return array list of found files
      */
     public function getFiles($directory, $fileExtension = '', $order = self::SORT_ASC)
@@ -2158,12 +2233,14 @@ class Pico
      *
      * @see https://secure.php.net/manual/en/function.glob.php
      *     PHP's glob() function
+     *
      * @param string $pattern the pattern to search for; see PHP's glob()
      *     function for details
      * @param int    $order   specify whether and how files should be sorted;
      *     use Pico::SORT_ASC for a alphabetical ascending order (this is the
      *     default behaviour), Pico::SORT_DESC for a descending order or
      *     Pico::SORT_NONE to leave the result unsorted
+     *
      * @return array list of found files
      */
     public function getFilesGlob($pattern, $order = self::SORT_ASC)
@@ -2192,6 +2269,7 @@ class Pico
      * This method also guarantees a trailing slash.
      *
      * @param string $path relative or absolute path
+     *
      * @return string absolute path
      */
     public function getAbsolutePath($path)
@@ -2222,8 +2300,10 @@ class Pico
      * @see PicoPluginInterface
      * @see AbstractPicoPlugin
      * @see DummyPlugin
+     *
      * @param string $eventName name of the event to trigger
      * @param array  $params    optional parameters to pass
+     *
      * @return void
      */
     public function triggerEvent($eventName, array $params = array())

lib/PicoPluginInterface.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * This file is part of Pico. It's copyrighted by the contributors recorded
+ * in the version control history of the file, available from the following
+ * original location:
+ *
+ * <https://github.com/picocms/Pico/blob/master/lib/PicoPluginInterface.php>
+ *
+ * SPDX-License-Identifier: MIT
+ * License-Filename: LICENSE
+ */
 
 /**
  * Common interface for Pico plugins
@@ -32,6 +42,7 @@ interface PicoPluginInterface
      *
      * @param string $eventName name of the triggered event
      * @param array  $params    passed parameters
+     *
      * @return void
      */
     public function handleEvent($eventName, array $params);
@@ -41,33 +52,38 @@ interface PicoPluginInterface
      *
      * @see PicoPluginInterface::isEnabled()
      * @see PicoPluginInterface::isStatusChanged()
-     * @param  boolean $enabled     enable (true) or disable (false) this plugin
-     * @param  boolean $recursive   when true, enable or disable recursively
+     *
+     * @param bool $enabled   enable (TRUE) or disable (FALSE) this plugin
+     * @param bool $recursive when TRUE, enable or disable recursively.
      *     In other words, if you enable a plugin, all required plugins are
      *     enabled, too. When disabling a plugin, all depending plugins are
      *     disabled likewise. Recursive operations are only performed as long
      *     as a plugin wasn't enabled/disabled manually. This parameter is
-     *     optional and defaults to true.
-     * @param  boolean $auto        enable or disable to fulfill a dependency
-     *     This parameter is optional and defaults to false.
+     *     optional and defaults to TRUE.
+     * @param bool $auto      enable or disable to fulfill a dependency. This
+     *     parameter is optional and defaults to FALSE.
+     *
      * @return void
+     *
      * @throws RuntimeException thrown when a dependency fails
      */
     public function setEnabled($enabled, $recursive = true, $auto = false);
 
     /**
-     * Returns true if this plugin is enabled, false otherwise
+     * Returns TRUE if this plugin is enabled, FALSE otherwise
      *
      * @see PicoPluginInterface::setEnabled()
-     * @return boolean plugin is enabled (true) or disabled (false)
+     *
+     * @return bool plugin is enabled (TRUE) or disabled (FALSE)
      */
     public function isEnabled();
 
     /**
-     * Returns true if the plugin was ever enabled/disabled manually
+     * Returns TRUE if the plugin was ever enabled/disabled manually
      *
      * @see PicoPluginInterface::setEnabled()
-     * @return boolean plugin is in its default state (true), false otherwise
+     *
+     * @return bool plugin is in its default state (TRUE), FALSE otherwise
      */
     public function isStatusChanged();
 
@@ -89,6 +105,7 @@ interface PicoPluginInterface
      * Returns the plugins instance of Pico
      *
      * @see Pico
+     *
      * @return Pico the plugins instance of Pico
      */
     public function getPico();

lib/PicoTwigExtension.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * This file is part of Pico. It's copyrighted by the contributors recorded
+ * in the version control history of the file, available from the following
+ * original location:
+ *
+ * <https://github.com/picocms/Pico/blob/master/lib/PicoTwigExtension.php>
+ *
+ * SPDX-License-Identifier: MIT
+ * License-Filename: LICENSE
+ */
 
 /**
  * Pico's Twig extension to implement additional filters
@@ -32,7 +42,8 @@ class PicoTwigExtension extends Twig_Extension
      * Returns the extensions instance of Pico
      *
      * @see Pico
-     * @return Pico the extensions instance of Pico
+     *
+     * @return Pico the extension's instance of Pico
      */
     public function getPico()
     {
@@ -43,6 +54,7 @@ class PicoTwigExtension extends Twig_Extension
      * Returns the name of the extension
      *
      * @see Twig_ExtensionInterface::getName()
+     *
      * @return string the extension name
      */
     public function getName()
@@ -54,6 +66,7 @@ class PicoTwigExtension extends Twig_Extension
      * Returns a list of Pico-specific Twig filters
      *
      * @see Twig_ExtensionInterface::getFilters()
+     *
      * @return Twig_SimpleFilter[] array of Pico's Twig filters
      */
     public function getFilters()
@@ -70,6 +83,7 @@ class PicoTwigExtension extends Twig_Extension
      * Returns a list of Pico-specific Twig functions
      *
      * @see Twig_ExtensionInterface::getFunctions()
+     *
      * @return Twig_SimpleFunction[] array of Pico's Twig functions
      */
     public function getFunctions()
@@ -90,8 +104,10 @@ class PicoTwigExtension extends Twig_Extension
      *
      * @see Pico::substituteFileContent()
      * @see Pico::parseFileContent()
+     *
      * @param string $markdown markdown to parse
      * @param array  $meta     meta data to use for %meta.*% replacement
+     *
      * @return string parsed HTML
      */
     public function markdownFilter($markdown, array $meta = array())
@@ -110,6 +126,7 @@ class PicoTwigExtension extends Twig_Extension
      * @param mixed             $mapKeyPath key to map; either a scalar or a
      *     array interpreted as key path (i.e. ['foo', 'bar'] will return all
      *     $item['foo']['bar'] values)
+     *
      * @return array mapped values
      */
     public function mapFilter($var, $mapKeyPath)
@@ -149,6 +166,7 @@ class PicoTwigExtension extends Twig_Extension
      *     to move these items to the end of the sorted array, "top" to rank
      *     them first, "keep" to keep the original order, or "remove" to remove
      *     these items
+     *
      * @return array sorted array
      */
     public function sortByFilter($var, $sortKeyPath, $fallback = 'bottom')
@@ -218,8 +236,9 @@ class PicoTwigExtension extends Twig_Extension
      * @param mixed                                $keyPath scalar key or a
      *     array interpreted as key path (when passing e.g. ['foo', 'bar'],
      *     the method will return $var['foo']['bar']) specifying the value
-     * @return mixed                                         the requested
-     *     value or NULL when the given key or key path didn't match
+     *
+     * @return mixed the requested value or NULL when the given key or key path
+     *     didn't match
      */
     public static function getKeyOfVar($var, $keyPath)
     {

plugins/DummyPlugin.php

@@ -1,4 +1,14 @@
 <?php
+/**
+ * This file is part of Pico. It's copyrighted by the contributors recorded
+ * in the version control history of the file, available from the following
+ * original location:
+ *
+ * <https://github.com/picocms/Pico/blob/master/plugins/DummyPlugin.php>
+ *
+ * SPDX-License-Identifier: MIT
+ * License-Filename: LICENSE
+ */
 
 /**
  * Pico dummy plugin - a template for plugins
@@ -27,7 +37,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * property.
      *
      * @see AbstractPicoPlugin::$enabled
-     * @var boolean
+     * @var bool
      */
     protected $enabled = false;
 
@@ -50,7 +60,9 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::getPlugin()
      * @see Pico::getPlugins()
+     *
      * @param object[] $plugins loaded plugin instances
+     *
      * @return void
      */
     public function onPluginsLoaded(array $plugins)
@@ -63,7 +75,9 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::getPlugin()
      * @see Pico::getPlugins()
+     *
      * @param object $plugin loaded plugin instance
+     *
      * @return void
      */
     public function onPluginManuallyLoaded($plugin)
@@ -75,7 +89,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has read its configuration
      *
      * @see Pico::getConfig()
+     *
      * @param array &$config array of config variables
+     *
      * @return void
      */
     public function onConfigLoaded(array &$config)
@@ -87,7 +103,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has evaluated the request URL
      *
      * @see Pico::getRequestUrl()
+     *
      * @param string &$url part of the URL describing the requested contents
+     *
      * @return void
      */
     public function onRequestUrl(&$url)
@@ -100,7 +118,9 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::getBaseUrl()
      * @see Pico::getRequestFile()
+     *
      * @param string &$file absolute path to the content file to serve
+     *
      * @return void
      */
     public function onRequestFile(&$file)
@@ -113,6 +133,7 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::loadFileContent()
      * @see DummyPlugin::onContentLoaded()
+     *
      * @return void
      */
     public function onContentLoading()
@@ -125,6 +146,7 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::load404Content()
      * @see DummyPlugin::on404ContentLoaded()
+     *
      * @return void
      */
     public function on404ContentLoading()
@@ -136,7 +158,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has read the contents of the 404 file
      *
      * @see Pico::getRawContent()
+     *
      * @param string &$rawContent raw file contents
+     *
      * @return void
      */
     public function on404ContentLoaded(&$rawContent)
@@ -152,7 +176,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * case when necessary.
      *
      * @see Pico::getRawContent()
+     *
      * @param string &$rawContent raw file contents
+     *
      * @return void
      */
     public function onContentLoaded(&$rawContent)
@@ -165,6 +191,7 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::parseFileMeta()
      * @see DummyPlugin::onMetaParsed()
+     *
      * @return void
      */
     public function onMetaParsing()
@@ -176,7 +203,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has parsed the meta header
      *
      * @see Pico::getFileMeta()
+     *
      * @param string[] &$meta parsed meta data
+     *
      * @return void
      */
     public function onMetaParsed(array &$meta)
@@ -190,6 +219,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see Pico::prepareFileContent()
      * @see DummyPlugin::prepareFileContent()
      * @see DummyPlugin::onContentParsed()
+     *
      * @return void
      */
     public function onContentParsing()
@@ -202,7 +232,9 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::parseFileContent()
      * @see DummyPlugin::onContentParsed()
+     *
      * @param string &$markdown Markdown contents of the requested page
+     *
      * @return void
      */
     public function onContentPrepared(&$markdown)
@@ -214,7 +246,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has parsed the contents of the file to serve
      *
      * @see Pico::getFileContent()
+     *
      * @param string &$content parsed contents (HTML) of the requested page
+     *
      * @return void
      */
     public function onContentParsed(&$content)
@@ -231,6 +265,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see DummyPlugin::onSinglePageLoaded()
      * @see DummyPlugin::onPagesDiscovered()
      * @see DummyPlugin::onPagesLoaded()
+     *
      * @return void
      */
     public function onPagesLoading()
@@ -251,9 +286,11 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see DummyPlugin::onSinglePageLoaded()
      * @see DummyPlugin::onPagesDiscovered()
      * @see DummyPlugin::onPagesLoaded()
+     *
      * @param string    $id       relative path to the content file
-     * @param  bool|null $skipPage set this to TRUE to remove this page from
-     *     the pages array, otherwise leave it unchanged
+     * @param bool|null $skipPage set this to TRUE to remove this page from the
+     *     pages array, otherwise leave it unchanged
+     *
      * @return void
      */
     public function onSinglePageLoading($id, &$skipPage)
@@ -271,8 +308,10 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see DummyPlugin::onSinglePageLoaded()
      * @see DummyPlugin::onPagesDiscovered()
      * @see DummyPlugin::onPagesLoaded()
+     *
      * @param string $id          relative path to the content file
      * @param string &$rawContent raw file contents
+     *
      * @return void
      */
     public function onSinglePageContent($id, &$rawContent)
@@ -286,7 +325,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * The `$pageData` parameter consists of the following values:
      *
      * | 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)            |
@@ -295,7 +334,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * | time           | string | timestamp derived from the Date header     |
      * | date           | string | date of the page (YAML header)             |
      * | date_formatted | string | formatted date of the page                 |
-     * | hidden         | boolean | this page shouldn't be visible to the user |
+     * | hidden         | bool   | this page shouldn't be visible to the user |
      * | raw_content    | string | raw, not yet parsed contents of the page   |
      * | meta           | string | parsed meta data of the page               |
      * | previous_page  | &array | reference to the previous page             |
@@ -304,11 +343,13 @@ class DummyPlugin extends AbstractPicoPlugin
      * Please note that the `previous_page` and `next_page` keys won't be
      * available until the `onCurrentPageDiscovered` event was triggered.
      *
-     * Set `$pageData` to `null` to remove this page from the pages array.
+     * Set `$pageData` to NULL to remove this page from the pages array.
      *
      * @see DummyPlugin::onPagesDiscovered()
      * @see DummyPlugin::onPagesLoaded()
+     *
      * @param array &$pageData data of the loaded page
+     *
      * @return void
      */
     public function onSinglePageLoaded(array &$pageData)
@@ -325,7 +366,9 @@ class DummyPlugin extends AbstractPicoPlugin
      *
      * @see Pico::sortPages()
      * @see DummyPlugin::onPagesLoaded()
+     *
      * @param array[] &$pages data of all known pages
+     *
      * @return void
      */
     public function onPagesDiscovered(array &$pages)
@@ -340,7 +383,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * structure of the page data.
      *
      * @see Pico::getPages()
+     *
      * @param array[] &$pages data of all known pages
+     *
      * @return void
      */
     public function onPagesLoaded(array &$pages)
@@ -359,9 +404,11 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see Pico::getCurrentPage()
      * @see Pico::getPreviousPage()
      * @see Pico::getNextPage()
+     *
      * @param array|null &$currentPage  data of the page being served
      * @param array|null &$previousPage data of the previous page
      * @param array|null &$nextPage     data of the next page
+     *
      * @return void
      */
     public function onCurrentPageDiscovered(
@@ -378,8 +425,10 @@ class DummyPlugin extends AbstractPicoPlugin
      * @see Pico::getTwigTemplate()
      * @see Pico::getTwigVariables()
      * @see DummyPlugin::onPageRendered()
+     *
      * @param string &$templateName  file name of the template
      * @param array  &$twigVariables template variables
+     *
      * @return void
      */
     public function onPageRendering(&$templateName, array &$twigVariables)
@@ -391,6 +440,7 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered after Pico has rendered the page
      *
      * @param string &$output contents which will be sent to the user
+     *
      * @return void
      */
     public function onPageRendered(&$output)
@@ -402,9 +452,11 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered when Pico reads its known meta header fields
      *
      * @see Pico::getMetaHeaders()
-     * @param  string[] &$headers list of known meta header
-     *     fields; the array key specifies the YAML key to search for, the
-     *     array value is later used to access the found value
+     *
+     * @param string[] &$headers list of known meta header fields; the array
+     *     key specifies the YAML key to search for, the array value is later
+     *     used to access the found value
+     *
      * @return void
      */
     public function onMetaHeaders(array &$headers)
@@ -416,7 +468,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered when Pico registers the YAML parser
      *
      * @see Pico::getYamlParser()
+     *
      * @param \Symfony\Component\Yaml\Parser &$yamlParser YAML parser instance
+     *
      * @return void
      */
     public function onYamlParserRegistered(\Symfony\Component\Yaml\Parser &$yamlParser)
@@ -428,7 +482,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered when Pico registers the Parsedown parser
      *
      * @see Pico::getParsedown()
+     *
      * @param Parsedown &$parsedown Parsedown instance
+     *
      * @return void
      */
     public function onParsedownRegistered(Parsedown &$parsedown)
@@ -440,7 +496,9 @@ class DummyPlugin extends AbstractPicoPlugin
      * Triggered when Pico registers the twig template engine
      *
      * @see Pico::getTwig()
+     *
      * @param Twig_Environment &$twig Twig instance
+     *
      * @return void
      */
     public function onTwigRegistered(Twig_Environment &$twig)