core: Improve documentation and style for BridgeAbstract and BridgeInterface

Public functions defined in BridgeAbstract also belong to BridgeInterface

getInput may only be used by this class or its children.

lib/BridgeAbstract.php

@@ -20,7 +20,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 	* @return mixed
 	*/
 	public function getCachable(){
-		return array("items" => $this->getItems(), "extraInfos" => $this->getExtraInfos());
+		return array(
+			'items' => $this->getItems(), 
+			'extraInfos' => $this->getExtraInfos()
+		);
 	}
 
 	/**
@@ -31,7 +34,13 @@ abstract class BridgeAbstract implements BridgeInterface {
 		return $this->items;
 	}
 
-
+	/**
+	 * Sets the input values for a given context. Existing values are 
+	 * overwritten.
+	 *
+	 * @param array $inputs Associative array of inputs
+	 * @param string $context The context name
+	 */
 	protected function setInputs(array $inputs, $queriedContext){
 		// Import and assign all inputs to their context
 		foreach($inputs as $name => $value){
@@ -106,10 +115,20 @@ abstract class BridgeAbstract implements BridgeInterface {
 		}
 	}
 
+	/**
+	 * Returns the name of the context matching the provided inputs
+	 *
+	 * @param array $inputs Associative array of inputs
+	 * @return mixed Returns the context name or null if no match was found
+	 */
 	protected function getQueriedContext(array $inputs){
 		$queriedContexts = array();
+
+		// Detect matching context
 		foreach(static::PARAMETERS as $context => $set){
 			$queriedContexts[$context] = null;
+
+			// Check if all parameters of the context are satisfied
 			foreach($set as $id => $properties){
 				if(isset($inputs[$id]) && !empty($inputs[$id])){
 					$queriedContexts[$context] = true;
@@ -119,8 +138,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 					break;
 				}
 			}
+
 		}
 
+		// Abort if one of the globally required parameters is not satisfied
 		if(array_key_exists('global', static::PARAMETERS)
 		&& $queriedContexts['global'] === false){
 			return null;
@@ -128,14 +149,15 @@ abstract class BridgeAbstract implements BridgeInterface {
 		unset($queriedContexts['global']);
 
 		switch(array_sum($queriedContexts)){
-		case 0:
+		case 0: // Found no match, is there a context without parameters?
 			foreach($queriedContexts as $context => $queried){
 				if(is_null($queried)){
 					return $context;
 				}
 			}
 			return null;
-		case 1: return array_search(true, $queriedContexts);
+		case 1: // Found unique match
+			return array_search(true, $queriedContexts);
 		default: return false;
 		}
 	}
@@ -193,7 +215,13 @@ abstract class BridgeAbstract implements BridgeInterface {
 		}
 	}
 
-	function getInput($input){
+	/**
+	 * Returns the value for the provided input
+	 *
+	 * @param string $input The input name
+	 * @return mixed Returns the input value or null if the input is not defined
+	 */
+	protected function getInput($input){
 		if(!isset($this->inputs[$this->queriedContext][$input]['value'])){
 			return null;
 		}
@@ -209,7 +237,10 @@ abstract class BridgeAbstract implements BridgeInterface {
 	}
 
 	public function getExtraInfos(){
-		return array("name" => $this->getName(), "uri" => $this->getURI());
+		return array(
+			'name' => $this->getName(), 
+			'uri' => $this->getURI()
+		);
 	}
 
 	public function setCache(\CacheInterface $cache){

lib/BridgeInterface.php

@@ -1,6 +1,50 @@
 <?php
 interface BridgeInterface {
+
+	/**
+	 * Collects data from the site
+	 */
 	public function collectData();
+
+	/**
+	 * Returns an array of cachable elements
+	 *
+	 * @return array Associative array of cachable elements
+	 */
+	public function getCachable();
+
+	/**
+	 * Return an array of extra information
+	 *
+	 * @return array Associative array of extra information
+	 */
+	public function getExtraInfos();
+
+	/**
+	 * Returns an array of collected items
+	 *
+	 * @return array Associative array of items
+	 */
+	public function getItems();
+
+	/**
+	 * Returns the bridge name
+	 *
+	 * @return string Bridge name
+	 */
 	public function getName();
+
+	/**
+	 * Returns the bridge URI
+	 *
+	 * @return string Bridge URI
+	 */
 	public function getURI();
+
+	/**
+	 * Sets the cache instance
+	 *
+	 * @param object CacheInterface The cache instance
+	 */
+	public function setCache(\CacheInterface $cache);
 }