From: Alexandre Emsenhuber Date: Sat, 9 Jan 2010 21:59:40 +0000 (+0000) Subject: * Document a bit X-Git-Tag: 1.31.0-rc.0~38338 X-Git-Url: https://git.cyclocoop.org/%7B%24admin_url%7Dmembres/fiche.php?a=commitdiff_plain;h=36d2910fa9ea4e1e41b74b807ec2e28a4d1aef8d;p=lhc%2Fweb%2Fwiklou.git * Document a bit * Add new doxygen group "Feed" * Fix some doxygen warnings --- diff --git a/includes/ChangesFeed.php b/includes/ChangesFeed.php index 9ff2724153..69a285e91e 100644 --- a/includes/ChangesFeed.php +++ b/includes/ChangesFeed.php @@ -1,14 +1,31 @@ format = $format; $this->type = $type; } + /** + * Get a ChannelFeed subclass object to use + * + * @param $title String: feed's title + * @param $description String: feed's description + * @return ChannelFeed subclass or false on failure + */ public function getFeedObject( $title, $description ) { global $wgSitename, $wgContLanguageCode, $wgFeedClasses, $wgTitle; $feedTitle = "$wgSitename - {$title} [$wgContLanguageCode]"; @@ -18,6 +35,18 @@ class ChangesFeed { $feedTitle, htmlspecialchars( $description ), $wgTitle->getFullUrl() ); } + /** + * Generates feed's content + * + * @param $feed ChannelFeed subclass object (generally the one returned by getFeedObject()) + * @param $rows ResultWrapper object with rows in recentchanges table + * @param $limit Integer: number of rows in $rows (only used for the cache key) + * @param $hideminor Boolean: whether to hide minor edits (only used for the cache key) + * @param $lastmod Integer: timestamp of the last item in the recentchanges table (only used for the cache key) + * @param $target String: target's name; for Special:RecentChangesLinked (only used for the cache key) + * @param $namespace Integer: namespace id (only used for the cache key) + * @return null or true + */ public function execute( $feed, $rows, $limit=0, $hideminor=false, $lastmod=false, $target='', $namespace='' ) { global $messageMemc, $wgFeedCacheTimeout; global $wgSitename, $wgLang; @@ -52,6 +81,13 @@ class ChangesFeed { return true; } + /** + * Save to feed result to $messageMemc + * + * @param $feed String: feed's content + * @param $timekey String: memcached key of the last modification + * @param $key String: memcached key of the content + */ public function saveToCache( $feed, $timekey, $key ) { global $messageMemc; $expire = 3600 * 24; # One day @@ -59,6 +95,14 @@ class ChangesFeed { $messageMemc->set( $timekey, wfTimestamp( TS_MW ), $expire ); } + /** + * Try to load the feed result from $messageMemc + * + * @param $lastmod Integer: timestamp of the last item in the recentchanges table + * @param $timekey String: memcached key of the last modification + * @param $key String: memcached key of the content + * @return feed's content on cache hit or false on cache miss + */ public function loadFromCache( $lastmod, $timekey, $key ) { global $wgFeedCacheTimeout, $messageMemc; $feedLastmod = $messageMemc->get( $timekey ); @@ -86,10 +130,10 @@ class ChangesFeed { } /** - * Generate the feed items given a row from the database. - * @param $rows Database resource with recentchanges rows - * @param $feed Feed object - */ + * Generate the feed items given a row from the database. + * @param $rows DatabaseBase resource with recentchanges rows + * @param $feed Feed object + */ public static function generateFeed( $rows, &$feed ) { wfProfileIn( __METHOD__ ); diff --git a/includes/Feed.php b/includes/Feed.php index fe6d8febd6..0289a6b916 100644 --- a/includes/Feed.php +++ b/includes/Feed.php @@ -19,13 +19,19 @@ # http://www.gnu.org/copyleft/gpl.html /** + * @defgroup Feed Feed + * * Basic support for outputting syndication feeds in RSS, other formats. * Contain a feed class as well as classes to build rss / atom ... feeds * Available feeds are defined in Defines.php + * + * @file */ /** * A base class for basic support for outputting syndication feeds in RSS and other formats. + * + * @ingroup Feed */ class FeedItem { /**#@+ @@ -39,9 +45,15 @@ class FeedItem { var $Author = ''; /**#@-*/ - /**#@+ - * @todo document - * @param $Url URL uniquely designating the item. + /** + * Constructor + * + * @param $Title String: Item's title + * @param $Description String + * @param $Url String: URL uniquely designating the item. + * @param $Date String: Item's date + * @param $Author String: Author's user name + * @param $Comments String */ function __construct( $Title, $Description, $Url, $Date = '', $Author = '', $Comments = '' ) { $this->Title = $Title; @@ -52,41 +64,87 @@ class FeedItem { $this->Comments = $Comments; } + /** + * Encode $string so that it can be safely embedded in a XML document + * + * @param $string String: string to encode + * @return String + */ public function xmlEncode( $string ) { $string = str_replace( "\r\n", "\n", $string ); $string = preg_replace( '/[\x00-\x08\x0b\x0c\x0e-\x1f]/', '', $string ); return htmlspecialchars( $string ); } + /** + * Get the title of this item; already xml-encoded + * + * @return String + */ public function getTitle() { return $this->xmlEncode( $this->Title ); } + /** + * Get the URL of this item; already xml-encoded + * + * @return String + */ public function getUrl() { return $this->xmlEncode( $this->Url ); } + /** + * Get the description of this item; already xml-encoded + * + * @return String + */ public function getDescription() { return $this->xmlEncode( $this->Description ); } + /** + * Get the language of this item + * + * @return String + */ public function getLanguage() { global $wgContLanguageCode; return $wgContLanguageCode; } + /** + * Get the title of this item + * + * @return String + */ public function getDate() { return $this->Date; } + + /** + * Get the author of this item; already xml-encoded + * + * @return String + */ public function getAuthor() { return $this->xmlEncode( $this->Author ); } + + /** + * Get the comment of this item; already xml-encoded + * + * @return String + */ public function getComments() { return $this->xmlEncode( $this->Comments ); } /** * Quickie hack... strip out wikilinks to more legible form from the comment. + * + * @param $text String: wikitext + * @return String */ public static function stripComment( $text ) { return preg_replace( '/\[\[([^]]*\|)?([^]]+)\]\]/', '\2', $text ); @@ -96,6 +154,7 @@ class FeedItem { /** * @todo document (needs one-sentence top-level class description). + * @ingroup Feed */ class ChannelFeed extends FeedItem { /**#@+ @@ -133,10 +192,8 @@ class ChannelFeed extends FeedItem { * * This should be called from the outHeader() method, * but can also be called separately. - * - * @public */ - function httpHeaders() { + public function httpHeaders() { global $wgOut; # We take over from $wgOut, excepting its cache header info @@ -178,13 +235,16 @@ class ChannelFeed extends FeedItem { /** * Generate a RSS feed + * + * @ingroup Feed */ class RSSFeed extends ChannelFeed { /** * Format a date given a timestamp - * @param integer $ts Timestamp - * @return string Date string + * + * @param $ts Integer: timestamp + * @return String: date string */ function formatTime( $ts ) { return gmdate( 'D, d M Y H:i:s \G\M\T', wfTimestamp( TS_UNIX, $ts ) ); @@ -210,7 +270,7 @@ class RSSFeed extends ChannelFeed { /** * Output an RSS 2.0 item - * @param FeedItem item to be output + * @param $item FeedItem: item to be output */ function outItem( $item ) { ?> @@ -237,6 +297,8 @@ class RSSFeed extends ChannelFeed { /** * Generate an Atom feed + * + * @ingroup Feed */ class AtomFeed extends ChannelFeed { /** diff --git a/includes/FeedUtils.php b/includes/FeedUtils.php index 4ed47d582e..072c00b152 100644 --- a/includes/FeedUtils.php +++ b/includes/FeedUtils.php @@ -1,8 +1,20 @@ getVal( 'action' ) === 'purge'; @@ -12,6 +24,12 @@ class FeedUtils { } } + /** + * Check whether feeds can be used and that $type is a valid feed type + * + * @param $type String: feed type, as requested by the user + * @return Boolean + */ public static function checkFeedOutput( $type ) { global $wgFeed, $wgFeedClasses; @@ -30,8 +48,11 @@ class FeedUtils { } /** - * Format a diff for the newsfeed - */ + * Format a diff for the newsfeed + * + * @param $row Object: row from the recentchanges table + * @return String + */ public static function formatDiff( $row ) { global $wgUser; @@ -53,6 +74,17 @@ class FeedUtils { $actiontext ); } + /** + * Really format a diff for the newsfeed + * + * @param $title Title object + * @param $oldid Integer: old revision's id + * @param $newid Integer: new revision's id + * @param $timestamp Integer: new revision's timestamp + * @param $comment String: new revision's comment + * @param $actiontext String: text of the action; in case of log event + * @return String + */ public static function formatDiffRow( $title, $oldid, $newid, $timestamp, $comment, $actiontext='' ) { global $wgFeedDiffCutoff, $wgContLang, $wgUser; wfProfileIn( __FUNCTION__ ); @@ -129,14 +161,14 @@ class FeedUtils { } /** - * Hacky application of diff styles for the feeds. - * Might be 'cleaner' to use DOM or XSLT or something, - * but *gack* it's a pain in the ass. - * - * @param $text String: - * @return string - * @private - */ + * Hacky application of diff styles for the feeds. + * Might be 'cleaner' to use DOM or XSLT or something, + * but *gack* it's a pain in the ass. + * + * @param $text String: diff's HTML output + * @return String: modified HTML + * @private + */ public static function applyDiffStyle( $text ) { $styles = array( 'diff' => 'background-color: white; color:black;',