From: Nick Jenkins Date: Wed, 28 Mar 2007 08:53:02 +0000 (+0000) Subject: PHPDocumentor [http://en.wikipedia.org/wiki/PhpDocumentor] documentation tweaking... X-Git-Tag: 1.31.0-rc.0~53567 X-Git-Url: http://git.cyclocoop.org/%22%20.%20generer_url_ecrire%28%22articles_versions%22%2C%22id_article=%24id_article%22%29%20.%20%22?a=commitdiff_plain;h=5fef2333d43faed0571878e848d6c40ade2c9810;p=lhc%2Fweb%2Fwiklou.git PHPDocumentor [en.wikipedia.org/wiki/PhpDocumentor] documentation tweaking stuff. 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) --- diff --git a/includes/AjaxDispatcher.php b/includes/AjaxDispatcher.php index 4a84ea2261..bb4709bb40 100644 --- a/includes/AjaxDispatcher.php +++ b/includes/AjaxDispatcher.php @@ -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; diff --git a/includes/AjaxResponse.php b/includes/AjaxResponse.php index c3c15ad3af..a814e57d4d 100644 --- a/includes/AjaxResponse.php +++ b/includes/AjaxResponse.php @@ -3,7 +3,9 @@ if( !defined( 'MEDIAWIKI' ) ) { die( 1 ); } -/** @todo document */ +/** + * @todo document + */ class AjaxResponse { var $mCacheDuration; var $mVary; diff --git a/includes/Article.php b/includes/Article.php index 3dd47a01b0..bef53e44bc 100644 --- a/includes/Article.php +++ b/includes/Article.php @@ -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. */ diff --git a/includes/Categoryfinder.php b/includes/Categoryfinder.php index 773c6b2837..fd75d77a31 100644 --- a/includes/Categoryfinder.php +++ b/includes/Categoryfinder.php @@ -1,26 +1,26 @@ 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 diff --git a/includes/ChangesList.php b/includes/ChangesList.php index 43fd543703..bc141579a3 100644 --- a/includes/ChangesList.php +++ b/includes/ChangesList.php @@ -1,10 +1,4 @@ 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. diff --git a/includes/DateFormatter.php b/includes/DateFormatter.php index 643da7b935..88a64453c9 100644 --- a/includes/DateFormatter.php +++ b/includes/DateFormatter.php @@ -1,11 +1,7 @@ * http://www.mediawiki.org/ @@ -27,6 +22,13 @@ * */ +/** + * 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; diff --git a/includes/EditPage.php b/includes/EditPage.php index 424695583b..74983ee188 100644 --- a/includes/EditPage.php +++ b/includes/EditPage.php @@ -1,16 +1,14 @@ # http://www.mediawiki.org/ # @@ -20,13 +19,13 @@ # 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 { /** diff --git a/includes/FileStore.php b/includes/FileStore.php index 1fd35b01f6..3d02bfa613 100644 --- a/includes/FileStore.php +++ b/includes/FileStore.php @@ -1,5 +1,8 @@ parse: parses wikitext to html - * parseinline: parses wikitext to html and removes the surrounding p's added by parser or tidy - * escape: filters message trough htmlspecialchars - * replaceafter: parameters are substituted after parsing or escaping - * parsemag: transform the message using magic phrases + * parse: parses wikitext to html + * parseinline: parses wikitext to html and removes the surrounding p's added by parser or tidy + * escape: filters message trough htmlspecialchars + * replaceafter: parameters are substituted after parsing or escaping + * parsemag: 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. */ diff --git a/includes/HTMLCacheUpdate.php b/includes/HTMLCacheUpdate.php index cc392d9609..9a0b6a0846 100644 --- a/includes/HTMLCacheUpdate.php +++ b/includes/HTMLCacheUpdate.php @@ -184,6 +184,9 @@ class HTMLCacheUpdate } } +/** + * @todo document (e.g. one-sentence top-level class description). + */ class HTMLCacheUpdateJob extends Job { var $table, $start, $end; diff --git a/includes/HistoryBlob.php b/includes/HistoryBlob.php index 3ce4ffd94d..282a7f5393 100644 --- a/includes/HistoryBlob.php +++ b/includes/HistoryBlob.php @@ -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; diff --git a/includes/IP.php b/includes/IP.php index 748a1f0b15..d9906c5343 100644 --- a/includes/IP.php +++ b/includes/IP.php @@ -1,8 +1,5 @@ * @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 diff --git a/includes/JobQueue.php b/includes/JobQueue.php index 54af5e73a7..b6ed6c32dd 100644 --- a/includes/JobQueue.php +++ b/includes/JobQueue.php @@ -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 ); diff --git a/includes/Licenses.php b/includes/Licenses.php index bd7494a3f3..f4586ae5e5 100644 --- a/includes/Licenses.php +++ b/includes/Licenses.php @@ -1,7 +1,7 @@ @@ -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 diff --git a/includes/LinkCache.php b/includes/LinkCache.php index 14072c56ea..53fb640a8f 100644 --- a/includes/LinkCache.php +++ b/includes/LinkCache.php @@ -1,10 +1,7 @@ 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 ) ); } diff --git a/includes/Parser.php b/includes/Parser.php index f5fbaa2a81..ece25fbd07 100644 --- a/includes/Parser.php +++ b/includes/Parser.php @@ -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). * * 
  * 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;
 
diff --git a/includes/ParserCache.php b/includes/ParserCache.php
index d31f7efe1d..752aa545f1 100644
--- a/includes/ParserCache.php
+++ b/includes/ParserCache.php
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * @todo document
  */
 class ParserCache {
 	/**
diff --git a/includes/ProfilerSimple.php b/includes/ProfilerSimple.php
index a118c85431..a52af257d5 100644
--- a/includes/ProfilerSimple.php
+++ b/includes/ProfilerSimple.php
@@ -1,13 +1,11 @@
 mString = $string;
@@ -791,6 +794,9 @@ class ImportStringSource {
 	}
 }
 
+/**
+ * @todo document (e.g. one-sentence class description).
+ */
 class ImportStreamSource {
 	function ImportStreamSource( $handle ) {
 		$this->mHandle = $handle;
diff --git a/includes/SpecialIpblocklist.php b/includes/SpecialIpblocklist.php
index 6ba3e55688..e5c285c0c2 100644
--- a/includes/SpecialIpblocklist.php
+++ b/includes/SpecialIpblocklist.php
@@ -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;
 
diff --git a/includes/SpecialListredirects.php b/includes/SpecialListredirects.php
index bc3969275d..09dc2b392e 100644
--- a/includes/SpecialListredirects.php
+++ b/includes/SpecialListredirects.php
@@ -8,9 +8,9 @@
  */
 
 /**
+ * Special:Listredirects - Lists all the redirects on the wiki.
  * @addtogroup SpecialPage
  */
-
 class ListredirectsPage extends QueryPage {
 
 	function getName() { return( 'Listredirects' ); }
diff --git a/includes/SpecialLockdb.php b/includes/SpecialLockdb.php
index 57c20b76c9..929e028f6f 100644
--- a/includes/SpecialLockdb.php
+++ b/includes/SpecialLockdb.php
@@ -36,7 +36,7 @@ function wfSpecialLockdb() {
 }
 
 /**
- *
+ * @todo document - e.g. a one-sentence top-level class description.
  * @addtogroup SpecialPage
  */
 class DBLockForm {
diff --git a/includes/SpecialLog.php b/includes/SpecialLog.php
index d258d5934e..fcce6df3da 100644
--- a/includes/SpecialLog.php
+++ b/includes/SpecialLog.php
@@ -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 {
diff --git a/includes/SpecialMIMEsearch.php b/includes/SpecialMIMEsearch.php
index 1e69b23eb6..d50efc0261 100644
--- a/includes/SpecialMIMEsearch.php
+++ b/includes/SpecialMIMEsearch.php
@@ -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;
diff --git a/includes/SpecialMovepage.php b/includes/SpecialMovepage.php
index 6a3e03e329..062a68aea8 100644
--- a/includes/SpecialMovepage.php
+++ b/includes/SpecialMovepage.php
@@ -41,7 +41,7 @@ function wfSpecialMovepage( $par = null ) {
 }
 
 /**
- *
+ * HTML form for Special:Movepage
  * @addtogroup SpecialPage
  */
 class MovePageForm {
diff --git a/includes/SpecialProtectedpages.php b/includes/SpecialProtectedpages.php
index 26c421248b..b214822da2 100644
--- a/includes/SpecialProtectedpages.php
+++ b/includes/SpecialProtectedpages.php
@@ -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;
diff --git a/includes/SpecialRandomredirect.php b/includes/SpecialRandomredirect.php
index 40df984055..60e9d6531b 100644
--- a/includes/SpecialRandomredirect.php
+++ b/includes/SpecialRandomredirect.php
@@ -5,7 +5,7 @@
  *
  * @addtogroup Special pages
  * @author Rob Church 
- * @licence GNU General Public Licence 2.0 or later
+ * @license GNU General Public Licence 2.0 or later
  */
 
 /**
diff --git a/includes/SpecialUndelete.php b/includes/SpecialUndelete.php
index e450884924..36d36690af 100644
--- a/includes/SpecialUndelete.php
+++ b/includes/SpecialUndelete.php
@@ -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 {
diff --git a/includes/SpecialUserlogin.php b/includes/SpecialUserlogin.php
index a34558f0f8..879886cd65 100644
--- a/includes/SpecialUserlogin.php
+++ b/includes/SpecialUserlogin.php
@@ -19,7 +19,7 @@ function wfSpecialUserlogin() {
 }
 
 /**
- *
+ * @todo document, briefly.
  * @addtogroup SpecialPage
  */
 
diff --git a/includes/SpecialVersion.php b/includes/SpecialVersion.php
index 5bc13186de..1aee8cdce7 100644
--- a/includes/SpecialVersion.php
+++ b/includes/SpecialVersion.php
@@ -4,8 +4,6 @@
  *
  * @addtogroup SpecialPage
  *
- * @bug 2019, 4531
- *
  * @author Ævar Arnfjörð Bjarmason 
  * @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
 	 */
diff --git a/includes/Title.php b/includes/Title.php
index 070cd2422f..8705dd0c23 100644
--- a/includes/Title.php
+++ b/includes/Title.php
@@ -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 ) );
diff --git a/includes/User.php b/includes/User.php
index a4630b84e2..8cdad6cf16 100644
--- a/includes/User.php
+++ b/includes/User.php
@@ -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();
diff --git a/includes/UserMailer.php b/includes/UserMailer.php
index b2d1a4f423..f3524f5782 100644
--- a/includes/UserMailer.php
+++ b/includes/UserMailer.php
@@ -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
diff --git a/includes/WebRequest.php b/includes/WebRequest.php
index 6c058af0c9..1962ce9421 100644
--- a/includes/WebRequest.php
+++ b/includes/WebRequest.php
@@ -21,6 +21,15 @@
 # 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,
@@ -32,15 +41,6 @@
  * 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();
diff --git a/includes/api/ApiBase.php b/includes/api/ApiBase.php
index c2dd93b09c..a29e3360cc 100644
--- a/includes/api/ApiBase.php
+++ b/includes/api/ApiBase.php
@@ -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.
diff --git a/includes/api/ApiFormatYaml_spyc.php b/includes/api/ApiFormatYaml_spyc.php
index 579fa5c1e5..fa049cffa4 100644
--- a/includes/api/ApiFormatYaml_spyc.php
+++ b/includes/api/ApiFormatYaml_spyc.php
@@ -14,13 +14,12 @@
    * @addtogroup Spyc
    */
   class YAMLNode {
-    /**#@+
+    /**
      * @access public
      * @var string
      */ 
     var $parent;
     var $id;
-    /**#@+*/
     /** 
      * @access public
      * @var mixed
@@ -328,7 +327,7 @@
   
     /**** Private Properties ****/
     
-    /**#@+
+    /**
      * @access private
      * @var mixed
      */ 
@@ -340,7 +339,6 @@
     var $_isInline;
     var $_dumpIndent;
     var $_dumpWordWrap;
-    /**#@+*/
 
     /**** Private Methods ****/