0ct0pu5/Pico
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve inline code comments; preparing use of phpDocumentor

Browse source
This commit is contained in:
Daniel Rudolf 2015-10-27 01:39:28 +01:00
parent 4171f9a031
commit 92af554d14
4 changed files with 95 additions and 50 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
lib/AbstractPicoPlugin.php
View file

@ -50,7 +50,7 @@ abstract class AbstractPicoPlugin implements PicoPluginInterface
/**
* List of plugin which depend on this plugin
*
* @var array<object>
* @var array<string, object>
* @see PicoPluginInterface::getDependants()
* @see AbstractPicoPlugin::checkDependants()
*/

94
lib/Pico.php
View file

@ -89,7 +89,7 @@ class Pico
* List of loaded plugins
*
* @see Pico::loadPlugins()
* @var array<object>
* @var array<object>|null
*/
protected $plugins;
@ -97,23 +97,23 @@ class Pico
* Current configuration of this Pico instance
*
* @see Pico::loadConfig()
* @var array
* @var array<string, mixed>|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<string, string>|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<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<string, mixed>|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<object>
* @return array<object>|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<string, mixed> $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<string, string> 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 <http://symfony.com/doc/current/components/yaml/introduction.html>
* @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<string, string> $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<string, mixed> template variables
*/
protected function getTwigVariables()
{

7
plugins/00-PicoDeprecated.php
View file

@ -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<string, mixed> &$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()
*/

42
plugins/DummyPlugin.php
View file

@ -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<string>
* @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<string, mixed> &$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<string> &$headers list of known meta header fields
* @param array<string, string> &$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<string, string> &$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<string, string> &$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<string, mixed> &$twigVariables template variables
* @param string &$templateName file name of the template
* @return void
*/
public function onPageRendering(&$twig, &$twigVariables, &$templateName)