lib: Add API documentation

lib/FeedExpander.php

@@ -1,11 +1,74 @@
 <?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
+ */
 
+/**
+ * An abstract class for bridges that need to transform existing RSS or Atom
+ * feeds.
+ *
+ * This class extends {@see BridgeAbstract} with functions to extract contents
+ * from existing RSS or Atom feeds. Bridges that need to transform existing feeds
+ * should inherit from this class instead of {@see BridgeAbstract}.
+ *
+ * Bridges that extend this class don't need to concern themselves with getting
+ * contents from existing feeds, but can focus on adding additional contents
+ * (i.e. by downloading additional data), filtering or just transforming a feed
+ * into another format.
+ *
+ * @link http://www.rssboard.org/rss-0-9-1 RSS 0.91 Specification
+ * @link http://web.resource.org/rss/1.0/spec RDF Site Summary (RSS) 1.0
+ * @link http://www.rssboard.org/rss-specification RSS 2.0 Specification
+ * @link https://tools.ietf.org/html/rfc4287 The Atom Syndication Format
+ *
+ * @todo Return `self` on more functions to allow chaining
+ * @todo The parsing functions should all be private. This class is complicated
+ * enough without having to consider children overriding functions.
+ */
 abstract class FeedExpander extends BridgeAbstract {
 
+	/**
+	 * Holds the title of the current feed
+	 *
+	 * @var string
+	 * @todo Rename this parameter to $title for clarity
+	 */
 	private $name;
+
+	/**
+	 * Holds the URI of the feed
+	 *
+	 * @var string
+	 */
 	private $uri;
+
+	/**
+	 * Holds the feed type during internal operations.
+	 *
+	 * @var string
+	 * @todo Define possible values as constant instead of static strings
+	 */
 	private $feedType;
 
+	/**
+	 * Collects data from an existing feed.
+	 *
+	 * Children should call this function in {@see BridgeInterface::collectData()}
+	 * to extract a feed.
+	 *
+	 * @param string $url URL to the feed.
+	 * @param int $maxItems Maximum number of items to collect from the feed
+	 * (`-1`: no limit).
+	 * @return void
+	 */
 	public function collectExpandableDatas($url, $maxItems = -1){
 		if(empty($url)) {
 			returnServerError('There is no $url for this RSS expander');
@@ -44,6 +107,19 @@ abstract class FeedExpander extends BridgeAbstract {
 		$this->{'collect_' . $this->feedType . '_data'}($rssContent, $maxItems);
 	}
 
+	/**
+	 * Collect data from a RSS 1.0 compatible feed
+	 *
+	 * @link http://web.resource.org/rss/1.0/spec RDF Site Summary (RSS) 1.0
+	 *
+	 * @param string $rssContent The RSS content
+	 * @param int $maxItems Maximum number of items to collect from the feed
+	 * (`-1`: no limit).
+	 * @return void
+	 *
+	 * @todo Instead of passing $maxItems to all functions, just add all items
+	 * and remove excessive items later.
+	 */
 	protected function collect_RSS_1_0_data($rssContent, $maxItems){
 		$this->load_RSS_2_0_feed_data($rssContent->channel[0]);
 		foreach($rssContent->item as $item) {
@@ -56,6 +132,19 @@ abstract class FeedExpander extends BridgeAbstract {
 		}
 	}
 
+	/**
+	 * Collect data from a RSS 2.0 compatible feed
+	 *
+	 * @link http://www.rssboard.org/rss-specification RSS 2.0 Specification
+	 *
+	 * @param object $rssContent The RSS content
+	 * @param int $maxItems Maximum number of items to collect from the feed
+	 * (`-1`: no limit).
+	 * @return void
+	 *
+	 * @todo Instead of passing $maxItems to all functions, just add all items
+	 * and remove excessive items later.
+	 */
 	protected function collect_RSS_2_0_data($rssContent, $maxItems){
 		$rssContent = $rssContent->channel[0];
 		Debug::log('RSS content is ===========\n'
@@ -73,6 +162,19 @@ abstract class FeedExpander extends BridgeAbstract {
 		}
 	}
 
+	/**
+	 * Collect data from a Atom 1.0 compatible feed
+	 *
+	 * @link https://tools.ietf.org/html/rfc4287  The Atom Syndication Format
+	 *
+	 * @param object $content The Atom content
+	 * @param int $maxItems Maximum number of items to collect from the feed
+	 * (`-1`: no limit).
+	 * @return void
+	 *
+	 * @todo Instead of passing $maxItems to all functions, just add all items
+	 * and remove excessive items later.
+	 */
 	protected function collect_ATOM_1_0_data($content, $maxItems){
 		$this->load_ATOM_feed_data($content);
 		foreach($content->entry as $item) {
@@ -85,16 +187,35 @@ abstract class FeedExpander extends BridgeAbstract {
 		}
 	}
 
+	/**
+	 * Convert RSS 2.0 time to timestamp
+	 *
+	 * @param object $item A feed item
+	 * @return int The timestamp
+	 */
 	protected function RSS_2_0_time_to_timestamp($item){
 		return DateTime::createFromFormat('D, d M Y H:i:s e', $item->pubDate)->getTimestamp();
 	}
 
-	// TODO set title, link, description, language, and so on
+	/**
+	 * Load RSS 2.0 feed data into RSS-Bridge
+	 *
+	 * @param object $rssContent The RSS content
+	 * @return void
+	 *
+	 * @todo set title, link, description, language, and so on
+	 */
 	protected function load_RSS_2_0_feed_data($rssContent){
 		$this->name = trim((string)$rssContent->title);
 		$this->uri = trim((string)$rssContent->link);
 	}
 
+	/**
+	 * Load Atom feed data into RSS-Bridge
+	 *
+	 * @param object $content The Atom content
+	 * @return void
+	 */
 	protected function load_ATOM_feed_data($content){
 		$this->name = (string)$content->title;
 
@@ -114,6 +235,16 @@ abstract class FeedExpander extends BridgeAbstract {
 		}
 	}
 
+	/**
+	 * Parse the contents of a single Atom feed item into a RSS-Bridge item for
+	 * further transformation.
+	 *
+	 * @param object $feedItem A single feed item
+	 * @return object The RSS-Bridge item
+	 *
+	 * @todo To reduce confusion, the RSS-Bridge item should maybe have a class
+	 * of its own?
+	 */
 	protected function parseATOMItem($feedItem){
 		// Some ATOM entries also contain RSS 2.0 fields
 		$item = $this->parseRSS_2_0_Item($feedItem);
@@ -139,6 +270,16 @@ abstract class FeedExpander extends BridgeAbstract {
 		return $item;
 	}
 
+	/**
+	 * Parse the contents of a single RSS 0.91 feed item into a RSS-Bridge item
+	 * for further transformation.
+	 *
+	 * @param object $feedItem A single feed item
+	 * @return object The RSS-Bridge item
+	 *
+	 * @todo To reduce confusion, the RSS-Bridge item should maybe have a class
+	 * of its own?
+	 */
 	protected function parseRSS_0_9_1_Item($feedItem){
 		$item = array();
 		if(isset($feedItem->link)) $item['uri'] = (string)$feedItem->link;
@@ -150,6 +291,16 @@ abstract class FeedExpander extends BridgeAbstract {
 		return $item;
 	}
 
+	/**
+	 * Parse the contents of a single RSS 1.0 feed item into a RSS-Bridge item
+	 * for further transformation.
+	 *
+	 * @param object $feedItem A single feed item
+	 * @return object The RSS-Bridge item
+	 *
+	 * @todo To reduce confusion, the RSS-Bridge item should maybe have a class
+	 * of its own?
+	 */
 	protected function parseRSS_1_0_Item($feedItem){
 		// 1.0 adds optional elements around the 0.91 standard
 		$item = $this->parseRSS_0_9_1_Item($feedItem);
@@ -164,6 +315,16 @@ abstract class FeedExpander extends BridgeAbstract {
 		return $item;
 	}
 
+	/**
+	 * Parse the contents of a single RSS 2.0 feed item into a RSS-Bridge item
+	 * for further transformation.
+	 *
+	 * @param object $feedItem A single feed item
+	 * @return object The RSS-Bridge item
+	 *
+	 * @todo To reduce confusion, the RSS-Bridge item should maybe have a class
+	 * of its own?
+	 */
 	protected function parseRSS_2_0_Item($feedItem){
 		// Primary data is compatible to 0.91 with some additional data
 		$item = $this->parseRSS_0_9_1_Item($feedItem);
@@ -211,9 +372,11 @@ abstract class FeedExpander extends BridgeAbstract {
 	}
 
 	/**
-	 * Method should return, from a source RSS item given by lastRSS, one of our Items objects
-	 * @param $item the input rss item
-	 * @return a RSS-Bridge Item, with (hopefully) the whole content)
+	 * Parse the contents of a single feed item, depending on the current feed
+	 * type, into a RSS-Bridge item.
+	 *
+	 * @param object $item The current feed item
+	 * @return object A RSS-Bridge item, with (hopefully) the whole content
 	 */
 	protected function parseItem($item){
 		switch($this->feedType) {
@@ -230,14 +393,17 @@ abstract class FeedExpander extends BridgeAbstract {
 		}
 	}
 
+	/** {@inheritdoc} */
 	public function getURI(){
 		return !empty($this->uri) ? $this->uri : parent::getURI();
 	}
 
+	/** {@inheritdoc} */
 	public function getName(){
 		return !empty($this->name) ? $this->name : parent::getName();
 	}
 
+	/** {@inheritdoc} */
 	public function getIcon(){
 		return !empty($this->icon) ? $this->icon : parent::getIcon();
 	}