From: Alexandre Emsenhuber Date: Sun, 7 Feb 2010 17:03:51 +0000 (+0000) Subject: * Fix some doxygen warnings X-Git-Tag: 1.31.0-rc.0~37890 X-Git-Url: http://git.cyclocoop.org/%24image?a=commitdiff_plain;h=79bbc9937eb4f389951c65c960a43dd7bb5b682c;p=lhc%2Fweb%2Fwiklou.git * Fix some doxygen warnings * Document a bit --- diff --git a/includes/Revision.php b/includes/Revision.php index 3e30361177..eeae08b3df 100644 --- a/includes/Revision.php +++ b/includes/Revision.php @@ -1,8 +1,4 @@ intval( $pageid ), 'page_id'=>intval( $pageid ) ); @@ -133,12 +125,10 @@ class Revision { * that's attached to a given page. If not attached * to that page, will return null. * - * @param Database $db - * @param Title $title - * @param int $id - * @return Revision - * @access public - * @static + * @param $db DatabaseBase + * @param $title Title + * @param $id Integer + * @return Revision or null */ public static function loadFromTitle( $db, $title, $id = 0 ) { if( $id ) { @@ -159,12 +149,10 @@ class Revision { * WARNING: Timestamps may in some circumstances not be unique, * so this isn't the best key to use. * - * @param Database $db - * @param Title $title - * @param string $timestamp - * @return Revision - * @access public - * @static + * @param $db Database + * @param $title Title + * @param $timestamp String + * @return Revision or null */ public static function loadFromTimestamp( $db, $title, $timestamp ) { return Revision::loadFromConds( @@ -178,10 +166,8 @@ class Revision { /** * Given a set of conditions, fetch a revision. * - * @param array $conditions - * @return Revision - * @access private - * @static + * @param $conditions Array + * @return Revision or null */ public static function newFromConds( $conditions ) { $db = wfGetDB( DB_SLAVE ); @@ -197,11 +183,9 @@ class Revision { * Given a set of conditions, fetch a revision from * the given database connection. * - * @param Database $db - * @param array $conditions - * @return Revision - * @access private - * @static + * @param $db Database + * @param $conditions Array + * @return Revision or null */ private static function loadFromConds( $db, $conditions ) { $res = Revision::fetchFromConds( $db, $conditions ); @@ -222,10 +206,8 @@ class Revision { * fetch all of a given page's revisions in turn. * Each row can be fed to the constructor to get objects. * - * @param Title $title + * @param $title Title * @return ResultWrapper - * @access public - * @static */ public static function fetchRevision( $title ) { return Revision::fetchFromConds( @@ -241,11 +223,9 @@ class Revision { * which will return matching database rows with the * fields necessary to build Revision objects. * - * @param Database $db - * @param array $conditions + * @param $db Database + * @param $conditions Array * @return ResultWrapper - * @access private - * @static */ private static function fetchFromConds( $db, $conditions ) { $fields = self::selectFields(); @@ -305,7 +285,9 @@ class Revision { } /** - * @param object $row + * Constructor + * + * @param $row Mixed: either a database row or an array * @access private */ function Revision( $row ) { @@ -378,13 +360,10 @@ class Revision { $this->mUnpatrolled = null; } - /**#@+ - * @access public - */ - /** * Get revision ID - * @return int + * + * @return Integer */ public function getId() { return $this->mId; @@ -392,7 +371,8 @@ class Revision { /** * Get text row ID - * @return int + * + * @return Integer */ public function getTextId() { return $this->mTextId; @@ -400,7 +380,8 @@ class Revision { /** * Get parent revision ID (the original previous page revision) - * @return int + * + * @return Integer */ public function getParentId() { return $this->mParentId; @@ -408,7 +389,8 @@ class Revision { /** * Returns the length of the text in this revision, or null if unknown. - * @return int + * + * @return Integer */ public function getSize() { return $this->mSize; @@ -416,6 +398,7 @@ class Revision { /** * Returns the title of the page associated with this entry. + * * @return Title */ public function getTitle() { @@ -438,7 +421,8 @@ class Revision { /** * Set the title of the revision - * @param Title $title + * + * @param $title Title */ public function setTitle( $title ) { $this->mTitle = $title; @@ -446,7 +430,8 @@ class Revision { /** * Get the page ID - * @return int + * + * @return Integer */ public function getPage() { return $this->mPage; @@ -457,13 +442,13 @@ class Revision { * If the specified audience does not have access to it, zero will be * returned. * - * @param integer $audience One of: + * @param $audience Integer: one of: * Revision::FOR_PUBLIC to be displayed to all users * Revision::FOR_THIS_USER to be displayed to $wgUser * Revision::RAW get the ID regardless of permissions * * - * @return int + * @return Integer */ public function getUser( $audience = self::FOR_PUBLIC ) { if( $audience == self::FOR_PUBLIC && $this->isDeleted( self::DELETED_USER ) ) { @@ -477,7 +462,8 @@ class Revision { /** * Fetch revision's user id without regard for the current user's permissions - * @return string + * + * @return String */ public function getRawUser() { return $this->mUser; @@ -488,7 +474,7 @@ class Revision { * If the specified audience does not have access to the username, an * empty string will be returned. * - * @param integer $audience One of: + * @param $audience Integer: one of: * Revision::FOR_PUBLIC to be displayed to all users * Revision::FOR_THIS_USER to be displayed to $wgUser * Revision::RAW get the text regardless of permissions @@ -507,7 +493,8 @@ class Revision { /** * Fetch revision's username without regard for view restrictions - * @return string + * + * @return String */ public function getRawUserText() { return $this->mUserText; @@ -518,12 +505,12 @@ class Revision { * If the specified audience does not have access to the comment, an * empty string will be returned. * - * @param integer $audience One of: + * @param $audience Integer: one of: * Revision::FOR_PUBLIC to be displayed to all users * Revision::FOR_THIS_USER to be displayed to $wgUser * Revision::RAW get the text regardless of permissions * - * @return string + * @return String */ function getComment( $audience = self::FOR_PUBLIC ) { if( $audience == self::FOR_PUBLIC && $this->isDeleted( self::DELETED_COMMENT ) ) { @@ -537,21 +524,22 @@ class Revision { /** * Fetch revision comment without regard for the current user's permissions - * @return string + * + * @return String */ public function getRawComment() { return $this->mComment; } /** - * @return bool + * @return Boolean */ public function isMinor() { return (bool)$this->mMinorEdit; } /** - * @return int rcid of the unpatrolled row, zero if there isn't one + * @return Integer rcid of the unpatrolled row, zero if there isn't one */ public function isUnpatrolled() { if( $this->mUnpatrolled !== null ) { @@ -573,7 +561,8 @@ class Revision { /** * int $field one of DELETED_* bitfield constants - * @return bool + * + * @return Boolean */ public function isDeleted( $field ) { return ( $this->mDeleted & $field ) == $field; @@ -581,7 +570,7 @@ class Revision { /** * Get the deletion bitfield of the revision - */ + */ public function getVisibility() { return (int)$this->mDeleted; } @@ -591,13 +580,13 @@ class Revision { * If the specified audience does not have the ability to view this * revision, an empty string will be returned. * - * @param integer $audience One of: + * @param $audience Integer: one of: * Revision::FOR_PUBLIC to be displayed to all users * Revision::FOR_THIS_USER to be displayed to $wgUser * Revision::RAW get the text regardless of permissions * * - * @return string + * @return String */ public function getText( $audience = self::FOR_PUBLIC ) { if( $audience == self::FOR_PUBLIC && $this->isDeleted( self::DELETED_TEXT ) ) { @@ -611,6 +600,8 @@ class Revision { /** * Alias for getText(Revision::FOR_THIS_USER) + * + * @return String */ public function revText() { return $this->getText( self::FOR_THIS_USER ); @@ -618,7 +609,8 @@ class Revision { /** * Fetch revision text without regard for view restrictions - * @return string + * + * @return String */ public function getRawText() { if( is_null( $this->mText ) ) { @@ -629,14 +621,14 @@ class Revision { } /** - * @return string + * @return String */ public function getTimestamp() { - return wfTimestamp(TS_MW, $this->mTimestamp); + return wfTimestamp( TS_MW, $this->mTimestamp ); } /** - * @return bool + * @return Boolean */ public function isCurrent() { return $this->mCurrent; @@ -644,7 +636,8 @@ class Revision { /** * Get previous revision for this title - * @return Revision + * + * @return Revision or null */ public function getPrevious() { if( $this->getTitle() ) { @@ -657,7 +650,9 @@ class Revision { } /** - * @return Revision + * Get next revision for this title + * + * @return Revision or null */ public function getNext() { if( $this->getTitle() ) { @@ -672,8 +667,9 @@ class Revision { /** * Get previous revision Id for this page_id * This is used to populate rev_parent_id on save - * @param Database $db - * @return int + * + * @param $db DatabaseBase + * @return Integer */ private function getPreviousRevisionId( $db ) { if( is_null( $this->mPage ) ) { @@ -698,9 +694,9 @@ class Revision { * $row is usually an object from wfFetchRow(), both the flags and the text * field must be included * - * @param object $row The text data - * @param string $prefix table prefix (default 'old_') - * @return string $text|false the text requested + * @param $row Object: the text data + * @param $prefix String: table prefix (default 'old_') + * @return String: text the text requested or false on failure */ public static function getRevisionText( $row, $prefix = 'old_' ) { wfProfileIn( __METHOD__ ); @@ -774,8 +770,8 @@ class Revision { * data is compressed, and 'utf-8' if we're saving in UTF-8 * mode. * - * @param mixed $text reference to a text - * @return string + * @param $text Mixed: reference to a text + * @return String */ public static function compressRevisionText( &$text ) { global $wgCompressRevisions; @@ -800,8 +796,8 @@ class Revision { * Insert a new revision into the database, returning the new revision ID * number on success and dies horribly on failure. * - * @param Database $dbw - * @return int + * @param $dbw DatabaseBase (master connection) + * @return Integer */ public function insertOn( $dbw ) { global $wgDefaultExternalStore; @@ -852,7 +848,7 @@ class Revision { 'rev_user_text' => $this->mUserText, 'rev_timestamp' => $dbw->timestamp( $this->mTimestamp ), 'rev_deleted' => $this->mDeleted, - 'rev_len' => $this->mSize, + 'rev_len' => $this->mSize, 'rev_parent_id' => is_null($this->mParentId) ? $this->getPreviousRevisionId( $dbw ) : $this->mParentId ), __METHOD__ @@ -870,7 +866,7 @@ class Revision { * Lazy-load the revision's text. * Currently hardcoded to the 'text' table storage engine. * - * @return string + * @return String */ protected function loadText() { wfProfileIn( __METHOD__ ); @@ -934,11 +930,11 @@ class Revision { * Such revisions can for instance identify page rename * operations and other such meta-modifications. * - * @param Database $dbw - * @param int $pageId ID number of the page to read from - * @param string $summary - * @param bool $minor - * @return mixed Revision, or null on error + * @param $dbw DatabaseBase + * @param $pageId Integer: ID number of the page to read from + * @param $summary String: revision's summary + * @param $minor Boolean: whether the revision should be considered as minor + * @return Mixed: Revision, or null on error */ public static function newNullRevision( $dbw, $pageId, $summary, $minor ) { wfProfileIn( __METHOD__ ); @@ -972,10 +968,11 @@ class Revision { /** * Determine if the current user is allowed to view a particular * field of this revision, if it's marked as deleted. - * @param int $field one of self::DELETED_TEXT, - * self::DELETED_COMMENT, - * self::DELETED_USER - * @return bool + * + * @param $field Integer:one of self::DELETED_TEXT, + * self::DELETED_COMMENT, + * self::DELETED_USER + * @return Boolean */ public function userCan( $field ) { return self::userCanBitfield( $this->mDeleted, $field ); @@ -985,11 +982,12 @@ class Revision { * Determine if the current user is allowed to view a particular * field of this revision, if it's marked as deleted. This is used * by various classes to avoid duplication. - * @param int $bitfield (current field) - * @param int $field one of self::DELETED_TEXT = File::DELETED_FILE, - * self::DELETED_COMMENT = File::DELETED_COMMENT, - * self::DELETED_USER = File::DELETED_USER - * @return bool + * + * @param $bitfield Integer: current field + * @param $field Integer: one of self::DELETED_TEXT = File::DELETED_FILE, + * self::DELETED_COMMENT = File::DELETED_COMMENT, + * self::DELETED_USER = File::DELETED_USER + * @return Boolean */ public static function userCanBitfield( $bitfield, $field ) { if( $bitfield & $field ) { // aspect is deleted @@ -1011,8 +1009,10 @@ class Revision { /** * Get rev_timestamp from rev_id, without loading the rest of the row - * @param Title $title - * @param integer $id + * + * @param $title Title + * @param $id Integer + * @return String */ static function getTimestampFromId( $title, $id ) { $dbr = wfGetDB( DB_SLAVE ); @@ -1033,8 +1033,10 @@ class Revision { /** * Get count of revisions per page...not very efficient - * @param Database $db - * @param int $id, page id + * + * @param $db DatabaseBase + * @param $id Integer: page id + * @return Integer */ static function countByPageId( $db, $id ) { $row = $db->selectRow( 'revision', 'COUNT(*) AS revCount', @@ -1047,8 +1049,10 @@ class Revision { /** * Get count of revisions per page...not very efficient - * @param Database $db - * @param Title $title + * + * @param $db DatabaseBase + * @param $title Title + * @return Integer */ static function countByTitle( $db, $title ) { $id = $title->getArticleId();