From 92af554d148aa6fe48c02b7a40d5671e941cbd64 Mon Sep 17 00:00:00 2001 From: Daniel Rudolf Date: Tue, 27 Oct 2015 01:39:28 +0100 Subject: [PATCH] Improve inline code comments; preparing use of phpDocumentor --- lib/AbstractPicoPlugin.php | 2 +- lib/Pico.php | 94 ++++++++++++++++++++++------------- plugins/00-PicoDeprecated.php | 7 +-- plugins/DummyPlugin.php | 42 ++++++++++++---- 4 files changed, 95 insertions(+), 50 deletions(-) diff --git a/lib/AbstractPicoPlugin.php b/lib/AbstractPicoPlugin.php index ef96838..cb19d44 100644 --- a/lib/AbstractPicoPlugin.php +++ b/lib/AbstractPicoPlugin.php @@ -50,7 +50,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface /** * List of plugin which depend on this plugin * - * @var array + * @var array * @see PicoPluginInterface::getDependants() * @see AbstractPicoPlugin::checkDependants() */ diff --git a/lib/Pico.php b/lib/Pico.php index 681cc34..ee15044 100644 --- a/lib/Pico.php +++ b/lib/Pico.php @@ -89,7 +89,7 @@ class Pico * List of loaded plugins * * @see Pico::loadPlugins() - * @var array + * @var array|null */ protected $plugins; @@ -97,23 +97,23 @@ class Pico * Current configuration of this Pico instance * * @see Pico::loadConfig() - * @var array + * @var array|null */ protected $config; /** - * URL with which the user requested the page + * Part of the URL describing the requested contents * * @see Pico::evaluateRequestUrl() - * @var string + * @var string|null */ protected $requestUrl; /** - * Path to the content file being served + * Absolute path to the content file being served * * @see Pico::discoverRequestFile() - * @var string + * @var string|null */ protected $requestFile; @@ -121,7 +121,7 @@ class Pico * Raw, not yet parsed contents to serve * * @see Pico::loadFileContent() - * @var string + * @var string|null */ protected $rawContent; @@ -129,7 +129,7 @@ class Pico * Meta data of the page to serve * * @see Pico::parseFileMeta() - * @var array + * @var array|null */ protected $meta; @@ -138,7 +138,7 @@ class Pico * * @see Pico::prepareFileContent() * @see Pico::parseFileContent() - * @var string + * @var string|null */ protected $content; @@ -146,7 +146,7 @@ class Pico * List of known pages * * @see Pico::readPages() - * @var array + * @var array|null */ protected $pages; @@ -154,7 +154,7 @@ class Pico * Data of the page being served * * @see Pico::discoverCurrentPage() - * @var array + * @var array|null */ protected $currentPage; @@ -162,7 +162,7 @@ class Pico * Data of the previous page relative to the page being served * * @see Pico::discoverCurrentPage() - * @var array + * @var array|null */ protected $previousPage; @@ -170,7 +170,7 @@ class Pico * Data of the next page relative to the page being served * * @see Pico::discoverCurrentPage() - * @var array + * @var array|null */ protected $nextPage; @@ -178,14 +178,14 @@ class Pico * Twig instance used for template parsing * * @see Pico::registerTwig() - * @var Twig_Environment + * @var Twig_Environment|null */ protected $twig; /** * Variables passed to the twig template * - * @var array + * @var array|null */ protected $twigVariables; @@ -193,6 +193,11 @@ class Pico * Constructs a new Pico instance * * To carry out all the processing in Pico, call the run() method. + * + * @param string $rootDir root directory of this Pico instance + * @param string $configDir config directory of this Pico instance + * @param string $pluginsDir plugins directory of this Pico instance + * @param string $themesDir themes directory of this Pico instance */ public function __construct($rootDir, $configDir, $pluginsDir, $themesDir) { @@ -398,7 +403,7 @@ class Pico * Returns all loaded plugins * * @see Pico::loadPlugins() - * @return array + * @return array|null */ public function getPlugins() { @@ -458,10 +463,11 @@ class Pico * call and Pico::run(). Options set with this method cannot be overwritten * by {@path "config/config.php"}. * - * @param array $config array with configuration variables, like - * $config in {@path "config/config.php"} + * @param array $config array with configuration variables, + * like $config in {@path "config/config.php"} * @return void - * @throws RuntimeException thrown if Pico already started processing + * @throws RuntimeException thrown if Pico already started + * processing */ public function setConfig(array $config) { @@ -534,7 +540,7 @@ class Pico * Returns the URL where a user requested the page * * @see Pico::evaluateRequestUrl() - * @return string request URL + * @return string|null request URL */ public function getRequestUrl() { @@ -567,10 +573,10 @@ class Pico } /** - * Returns the path to the content file to serve + * Returns the absolute path to the content file to serve * * @see Pico::discoverRequestFile() - * @return string file path + * @return string|null file path */ public function getRequestFile() { @@ -616,7 +622,7 @@ class Pico * Returns the cached raw contents, either of the requested or the 404 file * * @see Pico::loadFileContent() - * @return string raw contents + * @return string|null raw contents */ public function getRawContent() { @@ -629,7 +635,9 @@ class Pico * Heads up! Calling this method triggers the `onMetaHeaders` event. * Keep this in mind to prevent a infinite loop! * - * @return array known meta headers + * @return array known meta headers; the array value + * specifies the YAML key to search for, the array key is later used + * to access the found value */ public function getMetaHeaders() { @@ -657,9 +665,9 @@ class Pico * for users and pure (!) theme developers ONLY. * * @see - * @param string $rawContent the raw file contents - * @param array $headers a array containing the known headers - * @return array parsed meta data + * @param string $rawContent the raw file contents + * @param array $headers known meta headers + * @return array parsed meta data */ public function parseFileMeta($rawContent, array $headers) { @@ -707,7 +715,7 @@ class Pico * Returns the parsed meta data of the requested page * * @see Pico::parseFileMeta() - * @return array parsed meta data + * @return array|null parsed meta data */ public function getFileMeta() { @@ -772,7 +780,7 @@ class Pico * Returns the cached contents of the requested page * * @see Pico::parseFileContent() - * @return string parsed contents + * @return string|null parsed contents */ public function getFileContent() { @@ -782,6 +790,22 @@ class Pico /** * Reads the data of all pages known to Pico * + * The page data will be an array containing the following values: + * +----------------+------------------------------------------+ + * | Array key | Description | + * +----------------+------------------------------------------+ + * | id | relative path to the content file | + * | url | URL to the page | + * | title | title of the page (YAML header) | + * | description | description of the page (YAML header) | + * | author | author of the page (YAML header) | + * | time | timestamp derived from the Date header | + * | date | date of the page (YAML header) | + * | date_formatted | formatted date of the page | + * | raw_content | raw, not yet parsed contents of the page | + * | meta | parsed meta data of the page) | + * +----------------+------------------------------------------+ + * * @return void */ protected function readPages() @@ -884,7 +908,7 @@ class Pico * Returns the list of known pages * * @see Pico::readPages() - * @return array the data of all pages + * @return array|null the data of all pages */ public function getPages() { @@ -932,7 +956,7 @@ class Pico * Returns the data of the requested page * * @see Pico::discoverCurrentPage() - * @return array page data + * @return array|null page data */ public function getCurrentPage() { @@ -943,7 +967,7 @@ class Pico * Returns the data of the previous page relative to the page being served * * @see Pico::discoverCurrentPage() - * @return array page data + * @return array|null page data */ public function getPreviousPage() { @@ -954,7 +978,7 @@ class Pico * Returns the data of the next page relative to the page being served * * @see Pico::discoverCurrentPage() - * @return array page data + * @return array|null page data */ public function getNextPage() { @@ -977,7 +1001,7 @@ class Pico /** * Returns the twig template engine * - * @return Twig_Environment twig template engine + * @return Twig_Environment|null twig template engine */ public function getTwig() { @@ -990,7 +1014,7 @@ class Pico * URLs and paths (namely base_dir, base_url, theme_dir and theme_url) * don't add a trailing slash for historic reasons. * - * @return array template variables + * @return array template variables */ protected function getTwigVariables() { diff --git a/plugins/00-PicoDeprecated.php b/plugins/00-PicoDeprecated.php index edf05ea..f448abe 100644 --- a/plugins/00-PicoDeprecated.php +++ b/plugins/00-PicoDeprecated.php @@ -54,7 +54,7 @@ class PicoDeprecated extends AbstractPicoPlugin /** * The requested file * - * @var string + * @var string|null * @see PicoDeprecated::onRequestFile() */ protected $requestFile; @@ -139,7 +139,7 @@ class PicoDeprecated extends AbstractPicoPlugin /** * Read {@path "config.php"} in Picos root dir * - * @param array &$config array of config variables + * @param array &$config array of config variables * @return void */ protected function loadRootDirConfig(&$config) @@ -295,7 +295,8 @@ class PicoDeprecated extends AbstractPicoPlugin } /** - * Triggers the deprecated event get_pages($pages, $currentPage, $previousPage, $nextPage) + * Triggers the deprecated event + * get_pages($pages, $currentPage, $previousPage, $nextPage) * * @see DummyPlugin::onPagesLoaded() */ diff --git a/plugins/DummyPlugin.php b/plugins/DummyPlugin.php index 30771b1..588721d 100644 --- a/plugins/DummyPlugin.php +++ b/plugins/DummyPlugin.php @@ -16,6 +16,7 @@ class DummyPlugin extends AbstractPicoPlugin /** * This plugin is enabled by default? * + * @var boolean * @see AbstractPicoPlugin::$enabled */ protected $enabled = false; @@ -23,6 +24,7 @@ class DummyPlugin extends AbstractPicoPlugin /** * This plugin depends on {@link ...} * + * @var array * @see AbstractPicoPlugin::$dependsOn */ protected $dependsOn = array(); @@ -47,7 +49,7 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered after Pico has read its configuration * * @see Pico::getConfig() - * @param array &$config array of config variables + * @param array &$config array of config variables * @return void */ public function onConfigLoaded(&$config) @@ -60,7 +62,7 @@ class DummyPlugin extends AbstractPicoPlugin * * @see Pico::getBaseUrl() * @see Pico::getRequestUrl() - * @param string &$url request URL + * @param string &$url part of the URL describing the requested contents * @return void */ public function onRequestUrl(&$url) @@ -72,7 +74,7 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered after Pico has discovered the content file to serve * * @see Pico::getRequestFile() - * @param string &$file path to the content file to serve + * @param string &$file absolute path to the content file to serve * @return void */ public function onRequestFile(&$file) @@ -132,7 +134,9 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered when Pico reads its known meta header fields * * @see Pico::getMetaHeaders() - * @param array &$headers list of known meta header fields + * @param array &$headers list of known meta header + * fields; the array value specifies the YAML key to search for, the + * array key is later used to access the found value * @return void */ public function onMetaHeaders(&$headers) @@ -144,8 +148,8 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered before Pico parses the meta header * * @see Pico::parseFileMeta() - * @param string &$rawContent raw file contents - * @param array &$headers known meta header fields + * @param string &$rawContent raw file contents + * @param array &$headers known meta header fields * @return void */ public function onMetaParsing(&$rawContent, &$headers) @@ -157,7 +161,7 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered after Pico has parsed the meta header * * @see Pico::getFileMeta() - * @param array &$meta parsed meta data + * @param array &$meta parsed meta data * @return void */ public function onMetaParsed(&$meta) @@ -204,7 +208,20 @@ class DummyPlugin extends AbstractPicoPlugin /** * Triggered when Pico reads a single page from the list of all known pages * - * @param array &$pageData data of the loaded page + * @param array &$pageData { + * data of the loaded page + * + * @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 + * } * @return void */ public function onSinglePageLoaded(&$pageData) @@ -215,6 +232,9 @@ class DummyPlugin extends AbstractPicoPlugin /** * Triggered after Pico has read all known pages * + * See {@link DummyPlugin::onSinglePageLoaded()} for details about the + * structure of the page data. + * * @see Pico::getPages() * @see Pico::getCurrentPage() * @see Pico::getPreviousPage() @@ -244,9 +264,9 @@ class DummyPlugin extends AbstractPicoPlugin * Triggered before Pico renders the page * * @see Pico::getTwig() - * @param Twig_Environment &$twig twig template engine - * @param array &$twigVariables variables passed to the template - * @param string &$templateName name of the template to render + * @param Twig_Environment &$twig twig template engine + * @param array &$twigVariables template variables + * @param string &$templateName file name of the template * @return void */ public function onPageRendering(&$twig, &$twigVariables, &$templateName)