Add PHPDoc for every class.

simplepie · Jan 15, 2012 · 519cb25 · 519cb25
1 parent 9795fe8
commit 519cb25
Show file tree

Hide file tree

Showing 23 changed files with 187 additions and 18 deletions.
diff --git a/SimplePie/Author.php b/SimplePie/Author.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Manages all author-related data
+ *
+ * Used by {@see SimplePie_Item::get_author()} and {@see SimplePie::get_authors()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_author_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Author
 {
 	var $name;

diff --git a/SimplePie/Cache.php b/SimplePie/Cache.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Used to create cache objects
+ *
+ * This class can be overloaded with {@see SimplePie::set_cache_class()},
+ * although the preferred way is to create your own handler
+ * via {@see register()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Cache
 {
 	/**

diff --git a/SimplePie/Cache/Base.php b/SimplePie/Cache/Base.php
@@ -43,7 +43,14 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Base for cache objects
+ *
+ * Classes to be used with {@see SimplePie_Cache::register()} are expected
+ * to implement this interface.
+ *
+ * @package SimplePie
+ */
 interface SimplePie_Cache_Base
 {
 	/**

diff --git a/SimplePie/Cache/DB.php b/SimplePie/Cache/DB.php
@@ -43,8 +43,19 @@
  * @todo phpDoc comments
  */
 
+/**
+ * Base class for database-based caches
+ *
+ * @package SimplePie
+ */
 abstract class SimplePie_Cache_DB implements SimplePie_Cache_Base
 {
+	/**
+	 * Helper for database conversion
+	 *
+	 * Converts a given {@see SimplePie} object into data to be stored
+	 * @return array First item is the serialized data for storage, second item is the unique ID for this item
+	 */
 	protected static function prepare_simplepie_object_for_cache(&$data)
 	{
 		$items = $data->get_items();

diff --git a/SimplePie/Cache/File.php b/SimplePie/Cache/File.php
@@ -43,7 +43,11 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Caches data to the filesystem
+ *
+ * @package SimplePie
+ */
 class SimplePie_Cache_File implements SimplePie_Cache_Base
 {
 	protected $location;

diff --git a/SimplePie/Cache/Memcache.php b/SimplePie/Cache/Memcache.php
@@ -43,6 +43,17 @@
  * @todo phpDoc comments
  */
 
+/**
+ * Caches data to memcache
+ *
+ * Registered for URLs with the "memcache" protocol
+ *
+ * For example, `memcache://localhost:11211/?timeout=3600^prefix=sp_` will
+ * connect to memcache on `localhost` on port 11211. All tables will be
+ * prefixed with `sp_` and data will expire after 3600 seconds
+ *
+ * @package SimplePie
+ */
 class SimplePie_Cache_Memcache implements SimplePie_Cache_Base
 {
 	protected $cache;

diff --git a/SimplePie/Cache/MySQL.php b/SimplePie/Cache/MySQL.php
@@ -43,7 +43,17 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Caches data to a MySQL database
+ *
+ * Registered for URLs with the "mysql" protocol
+ *
+ * For example, `mysql://root:password@localhost:3306/mydb?prefix=sp_` will
+ * connect to the `mydb` database on `localhost` on port 3306, with the user
+ * `root` and the password `password`. All tables will be prefixed with `sp_`
+ *
+ * @package SimplePie
+ */
 class SimplePie_Cache_MySQL extends SimplePie_Cache_DB
 {
 	protected $mysql;

diff --git a/SimplePie/Caption.php b/SimplePie/Caption.php
@@ -44,6 +44,15 @@
  */
 
 
+/**
+ * Handles `<media:text>` captions as defined in Media RSS.
+ *
+ * Used by {@see SimplePie_Enclosure::get_caption()} and {@see SimplePie_Enclosure::get_captions()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_caption_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Caption
 {
 	var $type;

diff --git a/SimplePie/Category.php b/SimplePie/Category.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Manages all category-related data
+ *
+ * Used by {@see SimplePie_Item::get_category()} and {@see SimplePie_Item::get_categories()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_category_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Category
 {
 	var $term;

diff --git a/SimplePie/Content/Type/Sniffer.php b/SimplePie/Content/Type/Sniffer.php
@@ -48,6 +48,13 @@
  * Content-type sniffing
  *
  * Based on the rules in http://tools.ietf.org/html/draft-abarth-mime-sniff-06
+ *
+ * This is used since we can't always trust Content-Type headers, and is based
+ * upon the HTML5 parsing rules.
+ *
+ *
+ * This class can be overloaded with {@see SimplePie::set_content_type_sniffer_class()}
+ *
  * @package SimplePie
  */
 class SimplePie_Content_Type_Sniffer

diff --git a/SimplePie/Copyright.php b/SimplePie/Copyright.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Manages `<media:copyright>` copyright tags as defined in Media RSS
+ *
+ * Used by {@see SimplePie_Enclosure::get_copyright()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_copyright_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Copyright
 {
 	var $url;

diff --git a/SimplePie/Credit.php b/SimplePie/Credit.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Handles `<media:credit>` as defined in Media RSS
+ *
+ * Used by {@see SimplePie_Enclosure::get_credit()} and {@see SimplePie_Enclosure::get_credits()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_credit_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Credit
 {
 	var $role;

diff --git a/SimplePie/Enclosure.php b/SimplePie/Enclosure.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Handles everything related to enclosures (including Media RSS and iTunes RSS)
+ *
+ * Used by {@see SimplePie_Item::get_enclosure()} and {@see SimplePie_Item::get_enclosures()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_enclosure_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Enclosure
 {
 	var $bitrate;

diff --git a/SimplePie/File.php b/SimplePie/File.php
@@ -43,8 +43,14 @@
  * @todo phpDoc comments
  */
 
-
 /**
+ * Used for fetching remote files and reading local files
+ *
+ * Supports HTTP 1.0 via cURL or fsockopen, with spotty HTTP 1.1 support
+ *
+ * This class can be overloaded with {@see SimplePie::set_file_class()}
+ *
+ * @package SimplePie
  * @todo Move to properly supporting RFC2616 (HTTP/1.1)
  */
 class SimplePie_File

diff --git a/SimplePie/Item.php b/SimplePie/Item.php
@@ -44,6 +44,15 @@
  */
 
 
+/**
+ * Manages all item-related data
+ *
+ * Used by {@see SimplePie::get_item()} and {@see SimplePie::get_items()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_item_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Item
 {
 	var $feed;

diff --git a/SimplePie/Locator.php b/SimplePie/Locator.php
@@ -43,7 +43,14 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Used for feed auto-discovery
+ *
+ *
+ * This class can be overloaded with {@see SimplePie::set_locator_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Locator
 {
 	var $useragent;

diff --git a/SimplePie/Misc.php b/SimplePie/Misc.php
@@ -43,7 +43,11 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Miscellanous utilities
+ *
+ * @package SimplePie
+ */
 class SimplePie_Misc
 {
 	public static function time_hms($seconds)

diff --git a/SimplePie/Parser.php b/SimplePie/Parser.php
@@ -43,7 +43,14 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Parses XML into something sane
+ *
+ *
+ * This class can be overloaded with {@see SimplePie::set_parser_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Parser
 {
 	var $error_code;

diff --git a/SimplePie/Rating.php b/SimplePie/Rating.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Handles `<media:rating>` or `<itunes:explicit>` tags as defined in Media RSS and iTunes RSS respectively
+ *
+ * Used by {@see SimplePie_Enclosure::get_rating()} and {@see SimplePie_Enclosure::get_ratings()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_rating_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Rating
 {
 	var $scheme;

diff --git a/SimplePie/Restriction.php b/SimplePie/Restriction.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Handles `<media:restriction>` as defined in Media RSS
+ *
+ * Used by {@see SimplePie_Enclosure::get_restriction()} and {@see SimplePie_Enclosure::get_restrictions()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_restriction_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Restriction
 {
 	var $relationship;

diff --git a/SimplePie/Sanitize.php b/SimplePie/Sanitize.php
@@ -43,8 +43,13 @@
  * @todo phpDoc comments
  */
 
-
 /**
+ * Used for data cleanup and post-processing
+ *
+ *
+ * This class can be overloaded with {@see SimplePie::set_sanitize_class()}
+ *
+ * @package SimplePie
  * @todo Move to using an actual HTML parser (this will allow tags to be properly stripped, and to switch between HTML and XHTML), this will also make it easier to shorten a string while preserving HTML tags
  */
 class SimplePie_Sanitize

diff --git a/SimplePie/Source.php b/SimplePie/Source.php
@@ -43,7 +43,15 @@
  * @todo phpDoc comments
  */
 
-
+/**
+ * Handles `<atom:source>`
+ *
+ * Used by {@see SimplePie_Item::get_source()}
+ *
+ * This class can be overloaded with {@see SimplePie::set_source_class()}
+ *
+ * @package SimplePie
+ */
 class SimplePie_Source
 {
 	var $item;

diff --git a/SimplePie/gzdecode.php b/SimplePie/gzdecode.php
@@ -45,7 +45,7 @@
 
 
 /**
- * gzdecode
+ * Decode 'gzip' encoded HTTP data
  *
  * @package SimplePie
  */