PHPDocumentor [http://en.wikipedia.org/wiki/PhpDocumentor] documentation tweaking...
authorNick Jenkins <nickj@users.mediawiki.org>
Wed, 28 Mar 2007 08:53:02 +0000 (08:53 +0000)
committerNick Jenkins <nickj@users.mediawiki.org>
Wed, 28 Mar 2007 08:53:02 +0000 (08:53 +0000)
Minor doc tweaks to prevent some PHPDocumentor warnings or errors when run on the includes/ directory. PHPDocumentor uses a syntax very similar to javadoc - mostly we already use this, but there were a few scattered places that were adjusted to make them consistent with the rest of the code. In practical terms, these changes were made:
* @url becomes @link
* @fixme becomes @todo
* HTML tags in descriptions must be closed / balanced.
* @bug was removed (where the bug was long fixed), or changed into a @todo (in the few situations where the bug was still pending)
* @obsolete becomes @deprecated
* Things like "/**@{{" and "/**@}}*/" which cause "unknown tag" warnings were removed
* @access must be a valid access level.
* @desc tag not needed, removed.
* Doesn't seem to like @licence, will accept @license however.
* Use full comment block notation in a few places (i.e. open block with "/**", start each line with " *", and end block with " */")

Then additional to this, to get some class docs associated with their respective classes:
* Moved some docs to right above those classes (deleting blank lines, or moving descriptions from the file headers)
* Marked some classes without docs as "@todo document"
* (done up to "class MIMEsearchPage" on the "classtrees_MediaWiki.html" page for the includes/ directory)

53 files changed:
includes/AjaxDispatcher.php
includes/AjaxResponse.php
includes/Article.php
includes/Categoryfinder.php
includes/ChangesList.php
includes/Database.php
includes/DatabaseOracle.php
includes/DateFormatter.php
includes/DefaultSettings.php
includes/DifferenceEngine.php
includes/DjVuImage.php
includes/EditPage.php
includes/Exif.php
includes/Feed.php
includes/FileStore.php
includes/GlobalFunctions.php
includes/HTMLCacheUpdate.php
includes/HistoryBlob.php
includes/IP.php
includes/JobQueue.php
includes/Licenses.php
includes/LinkCache.php
includes/LinksUpdate.php
includes/LogPage.php
includes/OutputPage.php
includes/Parser.php
includes/ParserCache.php
includes/ProfilerSimple.php
includes/ProfilerSimpleUDP.php
includes/ProtectionForm.php
includes/Sanitizer.php
includes/SkinTemplate.php
includes/SpecialAncientpages.php
includes/SpecialBlockip.php
includes/SpecialEmailuser.php
includes/SpecialImport.php
includes/SpecialIpblocklist.php
includes/SpecialListredirects.php
includes/SpecialLockdb.php
includes/SpecialLog.php
includes/SpecialMIMEsearch.php
includes/SpecialMovepage.php
includes/SpecialProtectedpages.php
includes/SpecialRandomredirect.php
includes/SpecialUndelete.php
includes/SpecialUserlogin.php
includes/SpecialVersion.php
includes/Title.php
includes/User.php
includes/UserMailer.php
includes/WebRequest.php
includes/api/ApiBase.php
includes/api/ApiFormatYaml_spyc.php

index 4a84ea2..bb4709b 100644 (file)
@@ -9,6 +9,9 @@ if ( ! $wgUseAjax ) {
 
 require_once( 'AjaxFunctions.php' );
 
+/**
+ * @todo Document - e.g. Provide top-level description of this class.
+ */
 class AjaxDispatcher {
        var $mode;
        var $func_name;
index c3c15ad..a814e57 100644 (file)
@@ -3,7 +3,9 @@ if( !defined( 'MEDIAWIKI' ) ) {
        die( 1 );
 }
 
-/** @todo document */
+/**
+ * @todo document
+ */
 class AjaxResponse {
        var $mCacheDuration;
        var $mVary;
index 3dd47a0..bef53e4 100644 (file)
@@ -12,7 +12,7 @@
  *
  */
 class Article {
-       /**@{{
+       /**
         * @private
         */
        var $mComment;                  //!<
@@ -34,7 +34,7 @@ class Article {
        var $mTouched;                  //!<
        var $mUser;                             //!<
        var $mUserText;                 //!<
-       /**@}}*/
+       /** end private properties */
 
        /**
         * Constructor and clear the article
@@ -2348,7 +2348,7 @@ class Article {
         *
         * @param Revision $rev
         *
-        * @fixme This is a shitty interface function. Kill it and replace the
+        * @todo This is a shitty interface function. Kill it and replace the
         * other shitty functions like editUpdates and such so it's not needed
         * anymore.
         */
index 773c6b2..fd75d77 100644 (file)
@@ -1,26 +1,26 @@
 <?php
-/*
-The "Categoryfinder" class takes a list of articles, creates an internal representation of all their parent
-categories (as well as parents of parents etc.). From this representation, it determines which of these articles
-are in one or all of a given subset of categories.
-
-Example use :
-
-       # Determines wether the article with the page_id 12345 is in both
-       # "Category 1" and "Category 2" or their subcategories, respectively
-       
-       $cf = new Categoryfinder ;
-       $cf->seed (
-               array ( 12345 ) ,
-               array ( "Category 1","Category 2" ) ,
-               "AND"
-       ) ;
-       $a = $cf->run() ;
-       print implode ( "," , $a ) ;
-
-*/
-
 
+/**
+ * The "Categoryfinder" class takes a list of articles, creates an internal representation of all their parent
+ * categories (as well as parents of parents etc.). From this representation, it determines which of these articles
+ * are in one or all of a given subset of categories.
+ * 
+ * Example use :
+ * 
+ *     # Determines wether the article with the page_id 12345 is in both
+ *     # "Category 1" and "Category 2" or their subcategories, respectively
+ *     
+ *     $cf = new Categoryfinder ;
+ *     $cf->seed (
+ *             array ( 12345 ) ,
+ *             array ( "Category 1","Category 2" ) ,
+ *             "AND"
+ *     ) ;
+ *     $a = $cf->run() ;
+ *     print implode ( "," , $a ) ;
+ * 
+ * 
+ */
 class Categoryfinder {
 
        var $articles = array () ; # The original article IDs passed to the seed function
index 43fd543..bc14157 100644 (file)
@@ -1,10 +1,4 @@
 <?php
-/**
- * Contain class to show various lists of change:
- * - what's link here
- * - related changes
- * - recent changes
- */
 
 /**
  * @todo document
@@ -24,6 +18,10 @@ class RCCacheEntry extends RecentChange
 } ;
 
 /**
+ * Class to show various lists of changes:
+ * - what links here
+ * - related changes
+ * - recent changes
  */
 class ChangesList {
        # Called by history lists and recent changes
index 4bfc84b..0b1462c 100644 (file)
@@ -15,6 +15,9 @@ define( 'DEADLOCK_DELAY_MAX', 1500000 );
  * Utility classes
  *****************************************************************************/
 
+/**
+ * Utility class.
+ */
 class DBObject {
        public $mData;
 
@@ -31,6 +34,9 @@ class DBObject {
        }
 };
 
+/**
+ * Utility class.
+ */
 class MySQLField {
        private $name, $tablename, $default, $max_length, $nullable,
                $is_pk, $is_unique, $is_key, $type;
@@ -459,14 +465,12 @@ class Database {
 # Other functions
 #------------------------------------------------------------------------------
 
-       /**@{{
+       /**
+        * Constructor.
         * @param string $server database server host
         * @param string $user database user name
         * @param string $password database user password
         * @param string $dbname database name
-        */
-
-       /**
         * @param failFunction
         * @param $flags
         * @param $tablePrefix String: database table prefixes. By default use the prefix gave in LocalSettings.php
@@ -607,7 +611,6 @@ class Database {
                wfProfileOut( __METHOD__ );
                return $success;
        }
-       /**@}}*/
 
        /**
         * Closes a database connection.
@@ -1484,7 +1487,7 @@ class Database {
        }
        
        /**
-        * @desc: Fetch a number of table names into an zero-indexed numerical array
+        * Fetch a number of table names into an zero-indexed numerical array
         * This is handy when you need to construct SQL for joins
         *
         * Example:
index 7560039..a15978e 100644 (file)
@@ -3,7 +3,6 @@
 /**
  * This is the Oracle database abstraction layer.
  */
-
 class ORABlob {
        var $mData;
 
@@ -14,9 +13,9 @@ class ORABlob {
        function getData() {
                return $this->mData;
        }
-};
+}
 
-/*
+/**
  * The oci8 extension is fairly weak and doesn't support oci_num_rows, among 
  * other things.  We use a wrapper class to handle that and other 
  * Oracle-specific bits, like converting column names back to lowercase.
index 643da7b..88a6445 100644 (file)
@@ -1,11 +1,7 @@
 <?php
-/**
- * Date formatter, recognises dates in plain text and formats them accoding to user preferences.
- *
- * @addtogroup Parser
- */
 
 /**
+ * Date formatter, recognises dates in plain text and formats them accoding to user preferences.
  * @todo preferences, OutputPage
  * @addtogroup Parser
  */
index 4a2babc..20a7e5a 100644 (file)
@@ -307,8 +307,8 @@ $wgVerifyMimeType= true;
 /** Sets the mime type definition file to use by MimeMagic.php.
 * @global string $wgMimeTypeFile
 */
-#$wgMimeTypeFile= "/etc/mime.types";
 $wgMimeTypeFile= "includes/mime.types";
+#$wgMimeTypeFile= "/etc/mime.types";
 #$wgMimeTypeFile= NULL; #use built-in defaults only.
 
 /** Sets the mime type info file to use by MimeMagic.php.
index e6218b6..a065ab4 100644 (file)
@@ -1,6 +1,7 @@
 <?php
 /**
  * See diff.doc
+ * @todo indicate where diff.doc can be found.
  * @addtogroup DifferenceEngine
  */
 
@@ -1331,8 +1332,7 @@ class Diff
 }
 
 /**
- * FIXME: bad name.
- * @todo document
+ * @todo document, bad name.
  * @private
  * @addtogroup DifferenceEngine
  */
index 7872cf0..f983184 100644 (file)
@@ -1,11 +1,6 @@
 <?php
+
 /**
- * Support for detecting/validating DjVu image files and getting
- * some basic file metadata (resolution etc)
- *
- * File format docs are available in source package for DjVuLibre:
- * http://djvulibre.djvuzone.org/
- *
  *
  * Copyright (C) 2006 Brion Vibber <brion@pobox.com>
  * http://www.mediawiki.org/
  *
  */
 
+/**
+ * Support for detecting/validating DjVu image files and getting
+ * some basic file metadata (resolution etc)
+ *
+ * File format docs are available in source package for DjVuLibre:
+ * http://djvulibre.djvuzone.org/
+ */
 class DjVuImage {
        function __construct( $filename ) {
                $this->mFilename = $filename;
index 4246955..74983ee 100644 (file)
@@ -1,16 +1,14 @@
 <?php
 /**
- * Contain the EditPage class
+ * Contains the EditPage class
  */
 
 /**
- * Splitting edit page/HTML interface from Article...
+ * The edit page/HTML interface (split from Article)
  * The actual database and text munging is still in Article,
  * but it should get easier to call those from alternate
  * interfaces.
- *
  */
-
 class EditPage {
        var $mArticle;
        var $mTitle;
index 9bca6fd..84d8e8d 100644 (file)
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @link http://exif.org/Exif2-2.PDF The Exif 2.2 specification
- * @bug 1555, 1947
  */
 
 /**
+ * @todo document (e.g. one-sentence class-overview description)
  * @addtogroup Metadata
  */
 class Exif {
@@ -597,6 +597,7 @@ class Exif {
 }
 
 /**
+ * @todo document (e.g. one-sentence class-overview description)
  * @addtogroup Metadata
  */
 class FormatExif {
index 6967426..a77dcbc 100644 (file)
@@ -1,6 +1,5 @@
 <?php
-# Basic support for outputting syndication feeds in RSS, other formats
-#
+
 # Copyright (C) 2004 Brion Vibber <brion@pobox.com>
 # http://www.mediawiki.org/
 #
 # http://www.gnu.org/copyleft/gpl.html
 
 /**
+ * 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
  */
 
-
 /**
- * @todo document
+ * @todo document (needs one-sentence top-level class description + function descriptions).
  */
 class FeedItem {
        /**#@+
@@ -75,7 +74,7 @@ class FeedItem {
 }
 
 /**
- * @todo document
+ * @todo document (needs one-sentence top-level class description).
  */
 class ChannelFeed extends FeedItem {
        /**#@+
@@ -157,7 +156,6 @@ class ChannelFeed extends FeedItem {
 
 /**
  * Generate a RSS feed
- * @todo document
  */
 class RSSFeed extends ChannelFeed {
 
@@ -217,7 +215,6 @@ class RSSFeed extends ChannelFeed {
 
 /**
  * Generate an Atom feed
- * @todo document
  */
 class AtomFeed extends ChannelFeed {
        /**
index 1fd35b0..3d02bfa 100644 (file)
@@ -1,5 +1,8 @@
 <?php
 
+/**
+ * @todo document (needs one-sentence top-level class description).
+ */
 class FileStore {
        const DELETE_ORIGINAL = 1;
        
@@ -33,7 +36,7 @@ class FileStore {
         * suffer an uncaught error the lock will be released when the
         * connection is closed.
         *
-        * @fixme Probably only works on MySQL. Abstract to the Database class?
+        * @todo Probably only works on MySQL. Abstract to the Database class?
         */
        static function lock() {
                global $wgDBtype;
@@ -175,7 +178,7 @@ class FileStore {
         * @throws FSException if file can't be deleted
         * @return FSTransaction
         *
-        * @fixme Might be worth preliminary permissions check
+        * @todo Might be worth preliminary permissions check
         */
        static function deleteFile( $path ) {
                if( file_exists( $path ) ) {
index 345b763..58b5e2c 100644 (file)
@@ -558,11 +558,11 @@ function wfMsgWikiHtml( $key ) {
  * Returns message in the requested format
  * @param string $key Key of the message
  * @param array $options Processing rules:
- *  <i>parse<i>: parses wikitext to html
- *  <i>parseinline<i>: parses wikitext to html and removes the surrounding p's added by parser or tidy
- *  <i>escape<i>: filters message trough htmlspecialchars
- *  <i>replaceafter<i>: parameters are substituted after parsing or escaping
- *  <i>parsemag<i>: transform the message using magic phrases
+ *  <i>parse</i>: parses wikitext to html
+ *  <i>parseinline</i>: parses wikitext to html and removes the surrounding p's added by parser or tidy
+ *  <i>escape</i>: filters message trough htmlspecialchars
+ *  <i>replaceafter</i>: parameters are substituted after parsing or escaping
+ *  <i>parsemag</i>: transform the message using magic phrases
  */
 function wfMsgExt( $key, $options ) {
        global $wgOut, $wgParser;
@@ -612,7 +612,7 @@ function wfMsgExt( $key, $options ) {
  * Just like exit() but makes a note of it.
  * Commits open transactions except if the error parameter is set
  *
- * @obsolete Please return control to the caller or throw an exception
+ * @deprecated Please return control to the caller or throw an exception
  */
 function wfAbruptExit( $error = false ){
        global $wgLoadBalancer;
@@ -642,7 +642,7 @@ function wfAbruptExit( $error = false ){
 }
 
 /**
- * @obsolete Please return control the caller or throw an exception
+ * @deprecated Please return control the caller or throw an exception
  */
 function wfErrorExit() {
        wfAbruptExit( true );
@@ -1401,7 +1401,7 @@ define('TS_ISO_8601', 4);
 /**
  * An Exif timestamp (YYYY:MM:DD HH:MM:SS)
  *
- * @url http://exif.org/Exif2-2.PDF The Exif 2.2 spec, see page 28 for the
+ * @link http://exif.org/Exif2-2.PDF The Exif 2.2 spec, see page 28 for the
  *       DateTime tag and page 36 for the DateTimeOriginal and
  *       DateTimeDigitized tags.
  */
index cc392d9..9a0b6a0 100644 (file)
@@ -184,6 +184,9 @@ class HTMLCacheUpdate
        }
 }
 
+/**
+ * @todo document (e.g. one-sentence top-level class description).
+ */
 class HTMLCacheUpdateJob extends Job {
        var $table, $start, $end;
 
index 3ce4ffd..282a7f5 100644 (file)
@@ -5,6 +5,7 @@
 
 /**
  * Pure virtual parent
+ * @todo document (needs a one-sentence top-level class description, that answers the question: "what is a HistoryBlob?") 
  */
 class HistoryBlob
 {
@@ -48,6 +49,7 @@ class HistoryBlob
 
 /**
  * The real object
+ * @todo document (needs one-sentence top-level class description + function descriptions).
  */
 class ConcatenatedGzipHistoryBlob extends HistoryBlob
 {
@@ -176,6 +178,7 @@ $wgBlobCache = array();
 
 
 /**
+ * @todo document (needs one-sentence top-level class description + some function descriptions).
  */
 class HistoryBlobStub {
        var $mOldId, $mHash, $mRef;
@@ -193,16 +196,16 @@ class HistoryBlobStub {
                $this->mOldId = $id;
        }
 
-      /**
-       * Sets the location (old_id) of the referring object
-       */
+       /**
+        * Sets the location (old_id) of the referring object
+        */
        function setReferrer( $id ) {
                $this->mRef = $id;
        }
 
-      /**
-       * Gets the location of the referring object
-       */
+       /**
+        * Gets the location of the referring object
+        */
        function getReferrer() {
                return $this->mRef;
        }
@@ -269,7 +272,6 @@ class HistoryBlobStub {
  *
  * Serialized HistoryBlobCurStub objects will be inserted into the text table
  * on conversion if $wgFastSchemaUpgrades is set to true.
- *
  */
 class HistoryBlobCurStub {
        var $mCurId;
index 748a1f0..d9906c5 100644 (file)
@@ -1,8 +1,5 @@
 <?php
 /*
- * Collection of public static functions to play with IP address
- * and IP blocks.
- *
  * @Author "Ashar Voultoiz" <hashar@altern.org>
  * @License GPL v2 or later
  */
@@ -27,6 +24,10 @@ define( 'RE_IPV6_BLOCK', RE_IPV6_ADD . '\/' . RE_IPV6_PREFIX );
 // This might be useful for regexps used elsewhere, matches any IPv6 or IPv6 address or network
 define( 'IP_ADDRESS_STRING', RE_IP_ADD . '(\/' . RE_IP_PREFIX . '|)|' . RE_IPV6_ADD . '(\/' . RE_IPV6_PREFIX . '|)');
 
+/**
+ * A collection of public static functions to play with IP address
+ * and IP blocks.
+ */
 class IP {
        /**
         * Given a string, determine if it as valid IP
index 54af5e7..b6ed6c3 100644 (file)
@@ -4,6 +4,9 @@ if ( !defined( 'MEDIAWIKI' ) ) {
        die( "This file is part of MediaWiki, it is not a valid entry point\n" );
 }
 
+/**
+ * @todo document (e.g. one-sentence top-level class description).
+ */
 abstract class Job {
        var $command,
                $title,
@@ -238,6 +241,10 @@ abstract class Job {
        }
 }
 
+
+/**
+ * @todo document (e.g. one-sentence top-level class description).
+ */
 class RefreshLinksJob extends Job {
        function __construct( $title, $params = '', $id = 0 ) {
                parent::__construct( 'refreshLinks', $title, $params, $id );
index bd7494a..f4586ae 100644 (file)
@@ -1,7 +1,7 @@
 <?php
 /**
  * A License class for use on Special:Upload
- *
+ * 
  * @addtogroup SpecialPage
  *
  * @author Ævar Arnfjörð Bjarmason <avarab@gmail.com>
@@ -146,6 +146,9 @@ class Licenses {
        function getHtml() { return $this->html; }
 }
 
+/**
+ * A License class for use on Special:Upload (represents a single type of license).
+ */
 class License {
        /**
         * @var string
index 14072c5..53fb640 100644 (file)
@@ -1,10 +1,7 @@
 <?php
 /**
  * Cache for article titles (prefixed DB keys) and ids linked from one source
- * @addtogroup Cache
- */
-
-/**
+ * 
  * @addtogroup Cache
  */
 class LinkCache {
index bd6e241..755fb29 100644 (file)
@@ -1,14 +1,12 @@
 <?php
 /**
- * See deferred.txt
- */
-
-/**
- * @todo document
+ * See docs/deferred.txt
+ * 
+ * @todo document (e.g. one-sentence top-level class description).
  */
 class LinksUpdate {
 
-       /**@{{
+       /**
         * @private
         */
        var $mId,            //!< Page ID of the article linked from
@@ -22,7 +20,7 @@ class LinksUpdate {
                $mDb,            //!< Database connection reference
                $mOptions,       //!< SELECT options to be used (array)
                $mRecursive;     //!< Whether to queue jobs for recursive updates
-       /**@}}*/
+       /** end private attributes */
 
        /**
         * Constructor
index ecab3d8..af03bbb 100644 (file)
@@ -117,7 +117,7 @@ class LogPage {
        }
 
        /**
-        * @fixme: handle missing log types
+        * @todo handle missing log types
         * @static
         */
        function logHeader( $type ) {
index ba719a9..b94fd22 100644 (file)
@@ -766,7 +766,7 @@ class OutputPage {
                $this->returnToMain( false );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function errorpage( $title, $msg ) {
                throw new ErrorPageError( $title, $msg );
        }
@@ -876,7 +876,7 @@ class OutputPage {
                        $this->returnToMain( true, $mainPage );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function databaseError( $fname, $sql, $error, $errno ) {
                throw new MWException( "OutputPage::databaseError is obsolete\n" );
        }
@@ -940,32 +940,32 @@ class OutputPage {
                $this->returnToMain( false );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function fatalError( $message ) {
                throw new FatalError( $message ); 
        }
        
-       /** @obsolete */
+       /** @deprecated */
        public function unexpectedValueError( $name, $val ) {
                throw new FatalError( wfMsg( 'unexpected', $name, $val ) );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function fileCopyError( $old, $new ) {
                throw new FatalError( wfMsg( 'filecopyerror', $old, $new ) );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function fileRenameError( $old, $new ) {
                throw new FatalError( wfMsg( 'filerenameerror', $old, $new ) );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function fileDeleteError( $name ) {
                throw new FatalError( wfMsg( 'filedeleteerror', $name ) );
        }
 
-       /** @obsolete */
+       /** @deprecated */
        public function fileNotFoundError( $name ) {
                throw new FatalError( wfMsg( 'filenotfound', $name ) );
        }
index f5fbaa2..ece25fb 100644 (file)
@@ -56,9 +56,10 @@ define( 'MW_COLON_STATE_COMMENTDASH', 6 );
 define( 'MW_COLON_STATE_COMMENTDASHDASH', 7 );
 
 /**
- * PHP Parser
- *
- * Processes wiki markup
+ * PHP Parser - Processes wiki markup (which uses a more user-friendly 
+ * syntax, such as "[[link]]" for making links), and provides a one-way
+ * transformation of that wiki markup it into XHTML output / markup
+ * (which in turn the browser understands, and can display).
  *
  * <pre>
  * There are four main entry points into the Parser class:
@@ -1468,7 +1469,7 @@ class Parser
         * @param string
         * @return string
         * @static
-        * @fixme This can merge genuinely required bits in the path or query string,
+        * @todo  This can merge genuinely required bits in the path or query string,
         *        breaking legit URLs. A proper fix would treat the various parts of
         *        the URL differently; as a workaround, just use the output for
         *        statistical records, not for actual linking/output.
@@ -4702,6 +4703,9 @@ class Parser
 
 }
 
+/**
+ * @todo document, briefly.
+ */
 class OnlyIncludeReplacer {
        var $output = '';
 
@@ -4714,6 +4718,9 @@ class OnlyIncludeReplacer {
        }
 }
 
+/**
+ * @todo document, briefly.
+ */
 class StripState {
        var $general, $nowiki;
 
index d31f7ef..752aa54 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * @todo document
  */
 class ParserCache {
        /**
index a118c85..a52af25 100644 (file)
@@ -1,13 +1,11 @@
 <?php
-/**
- * Simple profiler base class
- */
 
-/**
- * @todo document
- */
 require_once(dirname(__FILE__).'/Profiler.php');
 
+/**
+ * Simple profiler base class.
+ * @todo document methods (?)
+ */
 class ProfilerSimple extends Profiler {
        var $mMinimumTime = 0;
        var $mProfileID = false;
index a9bce07..a8ca97f 100644 (file)
@@ -1,11 +1,12 @@
 <?php
-/* ProfilerSimpleUDP class, that sends out messages for 'udpprofile' daemon
-   (the one from mediawiki/trunk/udpprofile SVN )
-*/
 
 require_once(dirname(__FILE__).'/Profiler.php');
 require_once(dirname(__FILE__).'/ProfilerSimple.php');
 
+/**
+ * ProfilerSimpleUDP class, that sends out messages for 'udpprofile' daemon
+ * (the one from mediawiki/trunk/udpprofile SVN )
+ */
 class ProfilerSimpleUDP extends ProfilerSimple {
        function getFunctionReport() {
                global $wgUDPProfilerHost;
index 659ba1f..b2f5e2a 100644 (file)
@@ -21,6 +21,9 @@
  * @addtogroup SpecialPage
  */
 
+/**
+ * @todo document, briefly.
+ */
 class ProtectionForm {
        var $mRestrictions = array();
        var $mReason = '';
index 51c751c..b702188 100644 (file)
@@ -723,8 +723,6 @@ class Sanitizer {
         *                                                          name attributes
         * @link http://www.w3.org/TR/html401/struct/links.html#h-12.2.3 Anchors with the id attribute
         *
-        * @bug 4461
-        *
         * @static
         *
         * @param string $id
index 05eda0c..6023bf0 100644 (file)
@@ -66,7 +66,7 @@ class MediaWiki_I18N {
 }
 
 /**
- *
+ * @todo document with one-sentence top-level class description.
  */
 class SkinTemplate extends Skin {
        /**#@+
index 8894f5b..4b52b6a 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * @todo document, briefly.
  * @addtogroup SpecialPage
  */
 class AncientPagesPage extends QueryPage {
index 602f6db..5b73ef4 100644 (file)
@@ -37,7 +37,7 @@ function wfSpecialBlockip( $par ) {
 }
 
 /**
- * Form object
+ * Form object for the Special:Blockip page.
  *
  * @addtogroup SpecialPage
  */
index 2f4ce67..b49812b 100644 (file)
@@ -4,11 +4,11 @@
  * @addtogroup SpecialPage
  */
 
-/**
- *
- */
 require_once('UserMailer.php');
 
+/**
+ * @todo document
+ */
 function wfSpecialEmailuser( $par ) {
        global $wgUser, $wgOut, $wgRequest, $wgEnableEmail, $wgEnableUserEmail;
 
index 10ab239..44a6bc2 100644 (file)
@@ -771,6 +771,9 @@ class WikiImporter {
 
 }
 
+/**
+ * @todo document (e.g. one-sentence class description).
+ */
 class ImportStringSource {
        function ImportStringSource( $string ) {
                $this->mString = $string;
@@ -791,6 +794,9 @@ class ImportStringSource {
        }
 }
 
+/**
+ * @todo document (e.g. one-sentence class description).
+ */
 class ImportStreamSource {
        function ImportStreamSource( $handle ) {
                $this->mHandle = $handle;
index 6ba3e55..e5c285c 100644 (file)
@@ -45,7 +45,7 @@ function wfSpecialIpblocklist() {
 }
 
 /**
- *
+ * @todo document
  * @addtogroup SpecialPage
  */
 class IPUnblockForm {
@@ -319,6 +319,9 @@ class IPUnblockForm {
        }
 }
 
+/**
+ * @todo document
+ */
 class IPBlocklistPager extends ReverseChronologicalPager {
        public $mForm, $mConds;
 
index bc39692..09dc2b3 100644 (file)
@@ -8,9 +8,9 @@
  */
 
 /**
+ * Special:Listredirects - Lists all the redirects on the wiki.
  * @addtogroup SpecialPage
  */
-
 class ListredirectsPage extends QueryPage {
 
        function getName() { return( 'Listredirects' ); }
index 57c20b7..929e028 100644 (file)
@@ -36,7 +36,7 @@ function wfSpecialLockdb() {
 }
 
 /**
- *
+ * @todo document - e.g. a one-sentence top-level class description.
  * @addtogroup SpecialPage
  */
 class DBLockForm {
index d258d59..fcce6df 100644 (file)
@@ -36,7 +36,7 @@ function wfSpecialLog( $par = '' ) {
 }
 
 /**
- *
+ * @todo document (needs one-sentence top-level class description)
  * @addtogroup SpecialPage
  */
 class LogReader {
@@ -218,7 +218,7 @@ class LogReader {
 }
 
 /**
- *
+ * @todo document (needs one-sentence top-level class description)
  * @addtogroup SpecialPage
  */
 class LogViewer {
index 1e69b23..d50efc0 100644 (file)
@@ -10,6 +10,8 @@
  */
 
 /**
+ * Searches the database for files of the requested MIME type, comparing this with the
+ * 'img_major_mime' and 'img_minor_mime' fields in the image table.
  * @addtogroup SpecialPage
  */
 class MIMEsearchPage extends QueryPage {
@@ -77,7 +79,7 @@ class MIMEsearchPage extends QueryPage {
 }
 
 /**
- * constructor
+ * Output the HTML search form, and constructs the MIMEsearchPage object.
  */
 function wfSpecialMIMEsearch( $par = null ) {
        global $wgRequest, $wgTitle, $wgOut;
index 6a3e03e..062a68a 100644 (file)
@@ -41,7 +41,7 @@ function wfSpecialMovepage( $par = null ) {
 }
 
 /**
- *
+ * HTML form for Special:Movepage
  * @addtogroup SpecialPage
  */
 class MovePageForm {
index 26c4212..b214822 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * @todo document
  * @addtogroup SpecialPage
  */
 class ProtectedPagesForm {
@@ -185,8 +185,7 @@ class ProtectedPagesForm {
 }
 
 /**
- *
- *
+ * @todo document
  */
 class ProtectedPagesPager extends ReverseChronologicalPager {
        public $mForm, $mConds;
index 40df984..60e9d65 100644 (file)
@@ -5,7 +5,7 @@
  *
  * @addtogroup Special pages
  * @author Rob Church <robchur@gmail.com>
- * @licence GNU General Public Licence 2.0 or later
+ * @license GNU General Public Licence 2.0 or later
  */
 
 /**
index e450884..36d3669 100644 (file)
@@ -18,7 +18,7 @@ function wfSpecialUndelete( $par ) {
 }
 
 /**
- *
+ * @todo document (just needs one-sentence top-level class description)
  * @addtogroup SpecialPage
  */
 class PageArchive {
@@ -114,7 +114,7 @@ class PageArchive {
         * if not a file page.
         *
         * @return ResultWrapper
-        * @fixme Does this belong in Image for fuller encapsulation?
+        * @todo Does this belong in Image for fuller encapsulation?
         */
        function listFiles() {
                if( $this->title->getNamespace() == NS_IMAGE ) {
@@ -456,7 +456,8 @@ class PageArchive {
 }
 
 /**
- *
+ * The HTML form for Special:Undelete, which allows users with the appropriate
+ * permissions to view and restore deleted content.
  * @addtogroup SpecialPage
  */
 class UndeleteForm {
index a34558f..879886c 100644 (file)
@@ -19,7 +19,7 @@ function wfSpecialUserlogin() {
 }
 
 /**
- *
+ * @todo document, briefly.
  * @addtogroup SpecialPage
  */
 
index 5bc1318..1aee8cd 100644 (file)
@@ -4,8 +4,6 @@
  *
  * @addtogroup SpecialPage
  *
- * @bug 2019, 4531
- *
  * @author Ævar Arnfjörð Bjarmason <avarab@gmail.com>
  * @copyright Copyright © 2005, Ævar Arnfjörð Bjarmason
  * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License 2.0 or later
@@ -263,8 +261,6 @@ class SpecialVersion {
        /**
         * Retrieve the revision number of a Subversion working directory.
         *
-        * @bug 7335
-        *
         * @param string $dir
         * @return mixed revision number as int, or false if not a SVN checkout
         */
index 070cd24..8705dd0 100644 (file)
@@ -1229,7 +1229,7 @@ class Title {
        /**
         * Can $wgUser read this page?
         * @return boolean
-        * @fixme fold these checks into userCan()
+        * @todo fold these checks into userCan()
         */
        public function userCanRead() {
                global $wgUser;
@@ -1354,7 +1354,7 @@ class Title {
         * Cascading protection: Return true if cascading restrictions apply to this page, false if not.
         *
         * @return bool If the page is subject to cascading restrictions.
-        * @access public.
+        * @access public
         */
        function isCascadeProtected() {
                list( $sources, $restrictions ) = $this->getCascadeProtectionSources( false );
@@ -1902,7 +1902,8 @@ class Title {
         * members directly, which is what Linker::formatComment was doing previously.
         *
         * @param string $fragment text
-        * @access kind of public
+        * @access public
+        * @todo clarify whether access is supposed to be public (was marked as "kind of public")
         */
        function setFragment( $fragment ) {
                $this->mFragment = str_replace( '_', ' ', substr( $fragment, 1 ) );
index a4630b8..8cdad6c 100644 (file)
@@ -350,8 +350,6 @@ class User {
         * addresses like this, if we allowed accounts like this to be created
         * new users could get the old edits of these anonymous users.
         *
-        * @bug 3631
-        *
         * @static
         * @param string $name Nickname of a user
         * @return bool
@@ -499,8 +497,7 @@ class User {
         * rejected valid addresses. Actually just check if there is '@' somewhere
         * in the given address.
         *
-        * @todo Check for RFC 2822 compilance
-        * @bug 959
+        * @todo Check for RFC 2822 compilance (bug 959)
         *
         * @param string $addr email address
         * @static
@@ -602,7 +599,7 @@ class User {
 
        /**
         * Return a random password. Sourced from mt_rand, so it's not particularly secure.
-        * @todo: hash random numbers to improve security, like generateToken()
+        * @todo hash random numbers to improve security, like generateToken()
         *
         * @return string
         * @static
@@ -1651,7 +1648,7 @@ class User {
        /**
         * Add the user to the given group.
         * This takes immediate effect.
-        * @string $group
+        * @param string $group
         */
        function addGroup( $group ) {
                $this->load();
@@ -1675,7 +1672,7 @@ class User {
        /**
         * Remove the user from the given group.
         * This takes immediate effect.
-        * @string $group
+        * @param string $group
         */
        function removeGroup( $group ) {
                $this->load();
@@ -1946,7 +1943,7 @@ class User {
 
        /**
         * Save object settings into database
-        * @fixme Only rarely do all these fields need to be set!
+        * @todo Only rarely do all these fields need to be set!
         */
        function saveSettings() {
                $this->load();
index b2d1a4f..f3524f5 100644 (file)
@@ -32,6 +32,11 @@ function wfRFC822Phrase( $phrase ) {
        return '"' . $phrase . '"';
 }
 
+/**
+ * Stores a single person's name and email address.
+ * These are passed in via the constructor, and will be returned in SMTP
+ * header format when requested.
+ */
 class MailAddress {
        /**
         * @param mixed $address String with an email address, or a User object
@@ -191,14 +196,12 @@ function mailErrorHandler( $code, $string ) {
  *
  */
 class EmailNotification {
-       /**@{{
-        * @private
+       /**
+        * @private member variables:
         */
        var $to, $subject, $body, $replyto, $from;
        var $user, $title, $timestamp, $summary, $minorEdit, $oldid;
 
-       /**@}}*/
-
        /**
         * @todo document
         * @param $title Title object
index 6c058af..1962ce9 100644 (file)
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
 # http://www.gnu.org/copyleft/gpl.html
 
+
+/**
+ * Some entry points may use this file without first enabling the 
+ * autoloader.
+ */
+if ( !function_exists( '__autoload' ) ) {
+       require_once( dirname(__FILE__) . '/normal/UtfNormal.php' );
+}
+
 /**
  * The WebRequest class encapsulates getting at data passed in the
  * URL or via a POSTed form, handling remove of "magic quotes" slashes,
  * input.
  *
  */
-
-/**
- * Some entry points may use this file without first enabling the 
- * autoloader.
- */
-if ( !function_exists( '__autoload' ) ) {
-       require_once( dirname(__FILE__) . '/normal/UtfNormal.php' );
-}
-
 class WebRequest {
        function __construct() {
                $this->checkMagicQuotes();
index c2dd93b..a29e336 100644 (file)
@@ -24,6 +24,9 @@
  * http://www.gnu.org/copyleft/gpl.html
  */
 
+/**
+ * @todo Document - e.g. Provide top-level description of this class.
+ */
 abstract class ApiBase {
 
        // These constants allow modules to specify exactly how to treat incomming parameters.
index 579fa5c..fa049cf 100644 (file)
    * @addtogroup Spyc
    */
   class YAMLNode {
-    /**#@+
+    /**
      * @access public
      * @var string
      */ 
     var $parent;
     var $id;
-    /**#@+*/
     /** 
      * @access public
      * @var mixed
   
     /**** Private Properties ****/
     
-    /**#@+
+    /**
      * @access private
      * @var mixed
      */ 
     var $_isInline;
     var $_dumpIndent;
     var $_dumpWordWrap;
-    /**#@+*/
 
     /**** Private Methods ****/