lib: Add API documentation

lib/Configuration.php

@@ -1,10 +1,77 @@
 <?php
+/**
+ * This file is part of RSS-Bridge, a PHP project capable of generating RSS and
+ * Atom feeds for websites that don't have one.
+ *
+ * For the full license information, please view the UNLICENSE file distributed
+ * with this source code.
+ *
+ * @package	Core
+ * @license	http://unlicense.org/ UNLICENSE
+ * @link	https://github.com/rss-bridge/rss-bridge
+ */
+
+/**
+ * Configuration module for RSS-Bridge.
+ *
+ * This class implements a configuration module for RSS-Bridge.
+ *
+ * @todo Throw an exception if the caller tries to create objects of this class.
+ * @todo Make this class final.
+ */
 class Configuration {
 
+	/**
+	 * Holds the current release version of RSS-Bridge.
+	 *
+	 * Do not access this property directly!
+	 * Use {@see Configuration::getVersion()} instead.
+	 *
+	 * @var string
+	 *
+	 * @todo Replace this property by a constant.
+	 */
 	public static $VERSION = 'dev.2018-11-10';
 
+	/**
+	 * Holds the configuration data.
+	 *
+	 * Do not access this property directly!
+	 * Use {@see Configuration::getConfig()} instead.
+	 *
+	 * @var array|null
+	 *
+	 * @todo Change the scope of this property to protected or private
+	 */
 	public static $config = null;
 
+	/**
+	 * Verifies the current installation of RSS-Bridge and PHP.
+	 *
+	 * Returns an error message and aborts execution if the installation does
+	 * not satisfy the requirements of RSS-Bridge.
+	 *
+	 * **Requirements**
+	 * - PHP 5.6.0 or higher
+	 * - `openssl` extension
+	 * - `libxml` extension
+	 * - `mbstring` extension
+	 * - `simplexml` extension
+	 * - `curl` extension
+	 * - `json` extension
+	 * - The cache folder specified by {@see PATH_CACHE} requires write permission
+	 * - The whitelist file specified by {@see WHITELIST} requires write permission
+	 *
+	 * @link http://php.net/supported-versions.php PHP Supported Versions
+	 * @link http://php.net/manual/en/book.openssl.php OpenSSL
+	 * @link http://php.net/manual/en/book.libxml.php libxml
+	 * @link http://php.net/manual/en/book.mbstring.php Multibyte String (mbstring)
+	 * @link http://php.net/manual/en/book.simplexml.php SimpleXML
+	 * @link http://php.net/manual/en/book.curl.php Client URL Library (curl)
+	 * @link http://php.net/manual/en/book.json.php JavaScript Object Notation (json)
+	 *
+	 * @return void
+	 */
 	public static function verifyInstallation() {
 
 		// Check PHP version
@@ -40,6 +107,33 @@ class Configuration {
 
 	}
 
+	/**
+	 * Loads the configuration from disk and checks if the parameters are valid.
+	 *
+	 * Returns an error message and aborts execution if the configuration is invalid.
+	 *
+	 * The RSS-Bridge configuration is split into two files:
+	 * - `config.default.ini.php`: The default configuration file that ships with
+	 * every release of RSS-Bridge (do not modify this file!).
+	 * - `config.ini.php`: The local configuration file that can be modified by
+	 * server administrators.
+	 *
+	 * RSS-Bridge will first load `config.default.ini.php` into memory and then
+	 * replace parameters with the contents of `config.ini.php`. That way new
+	 * parameters are automatically initialized with default values and custom
+	 * configurations can be reduced to the minimum set of parametes necessary
+	 * (only the ones that changed).
+	 *
+	 * The configuration files must be placed in the root folder of RSS-Bridge
+	 * (next to `index.php`).
+	 *
+	 * _Notice_: The configuration is stored in {@see Configuration::$config}.
+	 *
+	 * @return void
+	 *
+	 * @todo Use {@see PATH_ROOT} to locate configuration files.
+	 * @todo Add documentation for constants defined by this function.
+	 */
 	public static function loadConfiguration() {
 
 		if(!file_exists('config.default.ini.php'))
@@ -97,6 +191,15 @@ class Configuration {
 
 	}
 
+	/**
+	 * Returns the value of a parameter identified by category and key.
+	 *
+	 * @param string $category The section name (category).
+	 * @param string $key The property name (key).
+	 * @return mixed|null The parameter value.
+	 *
+	 * @todo Rename $category to $section for clarity.
+	 */
 	public static function getConfig($category, $key) {
 
 		if(array_key_exists($category, self::$config) && array_key_exists($key, self::$config[$category])) {
@@ -107,6 +210,15 @@ class Configuration {
 
 	}
 
+	/**
+	 * Returns the current version string of RSS-Bridge.
+	 *
+	 * This function returns the contents of {@see Configuration::$VERSION} for
+	 * regular installations and the git branch name and commit id for instances
+	 * running in a git environment.
+	 *
+	 * @return string The version string.
+	 */
 	public static function getVersion() {
 
 		$headFile = '.git/HEAD';