[Bridge] Add and rewrite documentation compatible to phpDocumentor

This is the first step in adding documentation to the core library
of RSS-Bridge. The documentation is not yet extracted by phpdoc,
yet may prove useful to anyone interested in starting with RSS-Bridge.

1 files changed, 129 insertions, 17 deletions

diff --git a/lib/Bridge.php b/lib/Bridge.php
index 57d4d60b..88f48690 100644
--- a/lib/Bridge.php
+++ b/lib/Bridge.php
@@ -1,24 +1,80 @@
 <?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
+ */
+
+/**
+ * Factory class responsible for creating new instances of bridges from a given
+ * working directory, limited by a whitelist.
+ *
+ * This class is capable of:
+ * - Locating bridges in the specified working directory (see {@see Bridge::$dirBridge})
+ * - Filtering bridges based on a whitelist (see {@see Bridge::$whitelist})
+ * - Creating new bridge instances based on the bridge's name (see {@see Bridge::create()})
+ *
+ * The following example illustrates the intended use for this class.
+ *
+ * ```PHP
+ * require_once __DIR__ . '/rssbridge.php';
+ *
+ * // Step 1: Set the working directory
+ * Bridge::setDir(__DIR__ . '/../bridges/');
+ *
+ * // Step 2: Add bridges to the whitelist
+ * Bridge::setWhitelist(array('GitHubIssue', 'GoogleSearch', 'Facebook', 'Twitter'));
+ *
+ * // Step 3: Create a new instance of a bridge (based on the name)
+ * $bridge = Bridge::create('GitHubIssue');
+ * ```
+ */
 class Bridge {
 
+	/**
+	 * Holds the working directory.
+	 * Do not access this property directly!
+	 * Use {@see Bridge::setDir()} and {@see Bridge::getDir()} instead.
+	 *
+	 * @var string
+	 */
 	static protected $dirBridge;
 
 	/**
-	 * Holds the active whitelist.
-	 * Use Bridge::getWhitelist() instead of accessing this parameter directly!
+	 * Holds the whitelist.
+	 * Do not access this property directly!
+	 * Use {@see Bridge::getWhitelist()} instead.
+	 *
+	 * @var array
 	 */
 	private static $whitelist = array();
 
+	/**
+	 * Throws an exception when trying to create a new instance of this class.
+	 * Use {@see Bridge::create()} to instanciate a new bridge from the working
+	 * directory.
+	 *
+	 * @throws LogicException if called.
+	 */
 	public function __construct(){
 		throw new \LogicException('Please use ' . __CLASS__ . '::create for new object.');
 	}
 
 	/**
-	* Create a new bridge object
-	* @param string $nameBridge Defined bridge name you want use
-	* @return Bridge object dedicated
-	*/
+	 * Creates a new instance of a bridge in the working directory.
+	 *
+	 * @throws InvalidArgumentException if the provided bridge name is invalid.
+	 * @throws Exception if a bridge with the given name does not exist in the
+	 * working directory.
+	 * @param string $nameBridge Name of the bridge.
+	 * @return object|bool Instance of the bridge or false if the bridge is not instantiable.
+	 */
 	public static function create($nameBridge){
 		if(!preg_match('@^[A-Z][a-zA-Z0-9-]*$@', $nameBridge)) {
 			$message = <<<EOD
@@ -45,6 +101,14 @@ EOD;
 		return false;
 	}
 
+	/**
+	 * Sets the current working directory.
+	 *
+	 * @param string $dirBridge Path to the directory containing bridges.
+	 * @throws LogicException if the provided path is not a valid string.
+	 * @throws Exception if the provided path does not exist.
+	 * @return void
+	 */
 	public static function setDir($dirBridge){
 		if(!is_string($dirBridge)) {
 			throw new \InvalidArgumentException('Dir bridge must be a string.');
@@ -57,6 +121,13 @@ EOD;
 		self::$dirBridge = $dirBridge;
 	}
 
+	/**
+	 * Returns the current working directory.
+	 * The working directory must be specified with {@see Bridge::setDir()}!
+	 *
+	 * @throws LogicException if the working directory was not specified.
+	 * @return string The current working directory.
+	 */
 	public static function getDir(){
 		if(is_null(self::$dirBridge)) {
 			throw new \LogicException(__CLASS__ . ' class need to know bridge path !');
@@ -66,9 +137,12 @@ EOD;
 	}
 
 	/**
-	* Lists the available bridges.
-	* @return array List of the bridges
-	*/
+	 * Returns the list of bridge names based on the working directory.
+	 *
+	 * The list is cached internally to allow for successive calls.
+	 *
+	 * @return array List of bridge names
+	 */
 	public static function listBridges(){
 
 		static $listBridge = array(); // Initialized on first call
@@ -89,18 +163,29 @@ EOD;
 	}
 
 	/**
-	 * @return bool Returns true if the given bridge is whitelisted.
+	 * Checks if a bridge is whitelisted.
+	 *
+	 * @param string $name Name of the bridge.
+	 * @return bool True if the bridge is whitelisted.
 	 */
 	public static function isWhitelisted($name){
 		return in_array(Bridge::sanitizeBridgeName($name), Bridge::getWhitelist());
 	}
 
 	/**
-	 * On first call reads the whitelist from WHITELIST. Each line in the file
-	 * specifies one bridge that will be placed on the whitelist. An empty file
-	 * disables all bridges. '*' enables all bridges.
+	 * Returns the whitelist.
 	 *
-	 * @return array Returns a list of whitelisted bridges
+	 * On first call this function reads the whitelist from {@see WHITELIST}.
+	 * * Each line in the file specifies one bridge on the whitelist.
+	 * * An empty file disables all bridges.
+	 * * If the file only only contains `*`, all bridges are whitelisted.
+	 *
+	 * Use {@see Bridge::setWhitelist()} to specify a default whitelist **before**
+	 * calling this function! The list is cached internally to allow for
+	 * successive calls. If {@see Bridge::setWhitelist()} gets called after this
+	 * function, the whitelist is **not** updated again!
+	 *
+	 * @return array Array of whitelisted bridges
 	 */
 	public static function getWhitelist() {
 
@@ -129,13 +214,40 @@ EOD;
 
 	}
 
+	/**
+	 * Sets the (default) whitelist.
+	 *
+	 * If this function is called **before** {@see Bridge::getWhitelist()}, the
+	 * provided whitelist will be replaced by a custom whitelist specified in
+	 * {@see WHITELIST} (if it exists).
+	 *
+	 * If this function is called **after** {@see Bridge::getWhitelist()}, the
+	 * provided whitelist is taken as is (not updated by the custom whitelist
+	 * again).
+	 *
+	 * @param array $default The whitelist as array of bridge names.
+	 * @return void
+	 */
 	public static function setWhitelist($default = array()) {
 		Bridge::$whitelist = array_map('Bridge::sanitizeBridgeName', $default);
 	}
 
 	/**
-	 * @return string Returns a sanitized bridge name if the given name has been
-	 * found valid, null otherwise.
+	 * Returns the sanitized bridge name.
+	 *
+	 * The bridge name can be specified in various ways:
+	 * * The PHP file name (i.e. `GitHubIssueBridge.php`)
+	 * * The PHP file name without file extension (i.e. `GitHubIssueBridge`)
+	 * * The bridge name (i.e. `GitHubIssue`)
+	 *
+	 * Casing is ignored (i.e. `GITHUBISSUE` and `githubissue` are the same).
+	 *
+	 * A bridge file matching the given bridge name must exist in the working
+	 * directory!
+	 *
+	 * @param string $name The bridge name
+	 * @return string|null The sanitized bridge name if the provided name is
+	 * valid, null otherwise.
 	 */
 	private static function sanitizeBridgeName($name) {