lib: Add API documentation

lib/FormatAbstract.php

@@ -1,41 +1,95 @@
 <?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	https://unlicense.org/ UNLICENSE
+ * @link	https://github.com/rss-bridge/rss-bridge
+ */
 
+/**
+ * An abstract class for format implementations
+ *
+ * This class implements {@see FormatInterface}
+ */
 abstract class FormatAbstract implements FormatInterface {
+
+	/** The default charset (UTF-8) */
 	const DEFAULT_CHARSET = 'UTF-8';
 
-	protected
-		$contentType,
-		$charset,
-		$items,
-		$lastModified,
-		$extraInfos;
+	/** @var string $contentType The content type */
+	protected $contentType;
 
+	/** @var string $charset The charset */
+	protected $charset;
+
+	/** @var array $items The items */
+	protected $items;
+
+	/**
+	 * @var int $lastModified A timestamp to indicate the last modified time of
+	 * the output data.
+	 */
+	protected $lastModified;
+
+	/** @var array $extraInfos The extra infos */
+	protected $extraInfos;
+
+	/**
+	 * {@inheritdoc}
+	 *
+	 * @param string $charset {@inheritdoc}
+	 */
 	public function setCharset($charset){
 		$this->charset = $charset;
 
 		return $this;
 	}
 
+	/** {@inheritdoc} */
 	public function getCharset(){
 		$charset = $this->charset;
 
 		return is_null($charset) ? static::DEFAULT_CHARSET : $charset;
 	}
 
+	/**
+	 * Set the content type
+	 *
+	 * @param string $contentType The content type
+	 * @return self The format object
+	 */
 	protected function setContentType($contentType){
 		$this->contentType = $contentType;
 
 		return $this;
 	}
 
+	/**
+	 * Set the last modified time
+	 *
+	 * @param int $lastModified The last modified time
+	 * @return void
+	 */
 	public function setLastModified($lastModified){
 		$this->lastModified = $lastModified;
 	}
 
+	/**
+	 * Send header with the currently specified content type
+	 *
+	 * @return void
+	 * @todo This should throw an error if no content type is set
+	 */
 	protected function callContentType(){
 		header('Content-Type: ' . $this->contentType);
 	}
 
+	/** {@inheritdoc} */
 	public function display(){
 		if ($this->lastModified) {
 			header('Last-Modified: ' . gmdate('D, d M Y H:i:s ', $this->lastModified) . 'GMT');
@@ -45,12 +99,18 @@ abstract class FormatAbstract implements FormatInterface {
 		return $this;
 	}
 
+	/**
+	 * {@inheritdoc}
+	 *
+	 * @param array $items {@inheritdoc}
+	 */
 	public function setItems(array $items){
 		$this->items = array_map(array($this, 'array_trim'), $items);
 
 		return $this;
 	}
 
+	/** {@inheritdoc} */
 	public function getItems(){
 		if(!is_array($this->items))
 			throw new \LogicException('Feed the ' . get_class($this) . ' with "setItems" method before !');
@@ -59,10 +119,10 @@ abstract class FormatAbstract implements FormatInterface {
 	}
 
 	/**
-	* Define common informations can be required by formats and set default value for unknown values
-	* @param array $extraInfos array with know informations (there isn't merge !!!)
-	* @return this
-	*/
+	 * {@inheritdoc}
+	 *
+	 * @param array $extraInfos {@inheritdoc}
+	 */
 	public function setExtraInfos(array $extraInfos = array()){
 		foreach(array('name', 'uri', 'icon') as $infoName) {
 			if(!isset($extraInfos[$infoName])) {
@@ -75,10 +135,7 @@ abstract class FormatAbstract implements FormatInterface {
 		return $this;
 	}
 
-	/**
-	* Return extra infos
-	* @return array See "setExtraInfos" detail method to know what extra are disponibles
-	*/
+	/** {@inheritdoc} */
 	public function getExtraInfos(){
 		if(is_null($this->extraInfos)) { // No extra info ?
 			$this->setExtraInfos(); // Define with default value
@@ -88,12 +145,17 @@ abstract class FormatAbstract implements FormatInterface {
 	}
 
 	/**
-	 * Sanitized html while leaving it functionnal.
-	 * The aim is to keep html as-is (with clickable hyperlinks)
-	 * while reducing annoying and potentially dangerous things.
-	 * Yes, I know sanitizing HTML 100% is an impossible task.
-	 * Maybe we'll switch to http://htmlpurifier.org/
-	 * or http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed/index.php
+	 * Sanitize HTML while leaving it functional.
+	 *
+	 * Keeps HTML as-is (with clickable hyperlinks) while reducing annoying and
+	 * potentially dangerous things.
+	 *
+	 * @param string $html The HTML content
+	 * @return string The sanitized HTML content
+	 *
+	 * @todo This belongs into `html.php`
+	 * @todo Maybe switch to http://htmlpurifier.org/
+	 * @todo Maybe switch to http://www.bioinformatics.org/phplabware/internal_utilities/htmLawed/index.php
 	 */
 	protected function sanitizeHtml($html)
 	{
@@ -104,6 +166,17 @@ abstract class FormatAbstract implements FormatInterface {
 		return $html;
 	}
 
+	/**
+	 * Trim each element of an array
+	 *
+	 * This function applies `trim()` to all elements in the array, if the element
+	 * is a valid string.
+	 *
+	 * @param array $elements The array to trim
+	 * @return array The trimmed array
+	 *
+	 * @todo This is a utility function that doesn't belong here, find a new home.
+	 */
 	protected function array_trim($elements){
 		foreach($elements as $key => $value) {
 			if(is_string($value))