Added some comments to our classes.
authorAntoine Musso <hashar@users.mediawiki.org>
Sat, 21 Apr 2007 12:42:27 +0000 (12:42 +0000)
committerAntoine Musso <hashar@users.mediawiki.org>
Sat, 21 Apr 2007 12:42:27 +0000 (12:42 +0000)
12 files changed:
includes/Exception.php
includes/SpecialBrokenRedirects.php
includes/SpecialDoubleRedirects.php
includes/SpecialLockdb.php
includes/SpecialLonelypages.php
includes/SpecialPage.php
includes/SpecialResetpass.php
includes/SpecialUncategorizedpages.php
includes/SpecialUndelete.php
includes/SpecialUploadMogile.php
includes/StringUtils.php
includes/WebResponse.php

index 81cf12f..4cf0b7b 100644 (file)
@@ -1,6 +1,7 @@
 <?php
 
 /**
+ * MediaWiki exception
  * @addtogroup Exception
  */
 class MWException extends Exception
@@ -15,6 +16,7 @@ class MWException extends Exception
                return is_object( $wgLang );
        }
 
+       /** Get a message from i18n */
        function msg( $key, $fallback /*[, params...] */ ) {
                $args = array_slice( func_get_args(), 2 );
                if ( $this->useMessageCache() ) {
@@ -24,6 +26,7 @@ class MWException extends Exception
                }
        }
 
+       /* If wgShowExceptionDetails, return a HTML message with a backtrace to the error. */
        function getHTML() {
                global $wgShowExceptionDetails;
                if( $wgShowExceptionDetails ) {
@@ -36,6 +39,7 @@ class MWException extends Exception
                }
        }
 
+       /* If wgShowExceptionDetails, return a text message with a backtrace to the error */
        function getText() {
                global $wgShowExceptionDetails;
                if( $wgShowExceptionDetails ) {
@@ -46,7 +50,8 @@ class MWException extends Exception
                                "in LocalSettings.php to show detailed debugging information.</p>";
                }
        }
-       
+
+       /* Return titles of this error page */
        function getPageTitle() {
                if ( $this->useMessageCache() ) {
                        return wfMsg( 'internalerror' );
@@ -55,7 +60,10 @@ class MWException extends Exception
                        return "$wgSitename error";
                }
        }
-       
+
+       /** Return the requested URL and point to file and line number from which the
+        * exception occured
+        */
        function getLogMessage() {
                global $wgRequest;
                $file = $this->getFile();
@@ -63,7 +71,8 @@ class MWException extends Exception
                $message = $this->getMessage();
                return $wgRequest->getRequestURL() . " Exception from line $line of $file: $message";
        }
-       
+
+       /** Output the exception report using HTML */
        function reportHTML() {
                global $wgOut;
                if ( $this->useOutputPage() ) {
@@ -81,11 +90,15 @@ class MWException extends Exception
                        echo $this->htmlFooter();
                }
        }
-       
+
+       /** Print the exception report using text */
        function reportText() {
                echo $this->getText();
        }
 
+       /* Output a report about the exception and takes care of formatting.
+        * It will be either HTML or plain text based on $wgCommandLineMode.
+        */
        function report() {
                global $wgCommandLineMode;
                if ( $wgCommandLineMode ) {
@@ -210,7 +223,7 @@ function wfReportException( Exception $e ) {
 function wfExceptionHandler( $e ) {
        global $wgFullyInitialised;
        wfReportException( $e );
-       
+
        // Final cleanup, similar to wfErrorExit()
        if ( $wgFullyInitialised ) {
                try {
index 12dba8a..208a7e1 100644 (file)
@@ -5,7 +5,8 @@
  */
 
 /**
- *
+ * A special page listing redirects to non existent page. Those should be
+ * fixed to point to an existing page.
  * @addtogroup SpecialPage
  */
 class BrokenRedirectsPage extends PageQueryPage {
index 5bb199c..2a7d172 100644 (file)
@@ -5,7 +5,8 @@
  */
 
 /**
- *
+ * A special page listing redirects to redirecting page.
+ * The software will not procede double redirects automaticly to prevent loops.
  * @addtogroup SpecialPage
  */
 class DoubleRedirectsPage extends PageQueryPage {
index 929e028..db4006f 100644 (file)
@@ -36,7 +36,7 @@ function wfSpecialLockdb() {
 }
 
 /**
- * @todo document - e.g. a one-sentence top-level class description.
+ * A form to make the database readonly (eg for maintenance purposes).
  * @addtogroup SpecialPage
  */
 class DBLockForm {
index 810bd1e..430af7a 100644 (file)
@@ -5,7 +5,8 @@
  */
 
 /**
- *
+ * A special page looking for articles with no article linking to them,
+ * thus being lonely.
  * @addtogroup SpecialPage
  */
 class LonelyPagesPage extends PageQueryPage {
index faf4517..cf88250 100644 (file)
@@ -714,6 +714,7 @@ class IncludableSpecialPage extends SpecialPage
 }
 
 /**
+ * Shortcut to construct a special page alias.
  * @addtogroup SpecialPage
  */
 class SpecialRedirectToSpecial extends UnlistedSpecialPage {
@@ -735,7 +736,15 @@ class SpecialRedirectToSpecial extends UnlistedSpecialPage {
        }
 }
 
+/** SpecialMypage, SpecialMytalk and SpecialMycontributions special pages
+ * are used to get user independant links pointing to the user page, talk
+ * page and list of contributions.
+ * This can let us cache a single copy of any generated content for all
+ * users.
+ */
+
 /**
+ * Shortcut to construct a special page pointing to current user user's page.
  * @addtogroup SpecialPage
  */
 class SpecialMypage extends UnlistedSpecialPage {
@@ -755,6 +764,7 @@ class SpecialMypage extends UnlistedSpecialPage {
 }
 
 /**
+ * Shortcut to construct a special page pointing to current user talk page.
  * @addtogroup SpecialPage
  */
 class SpecialMytalk extends UnlistedSpecialPage {
@@ -774,6 +784,7 @@ class SpecialMytalk extends UnlistedSpecialPage {
 }
 
 /**
+ * Shortcut to construct a special page pointing to current user contributions.
  * @addtogroup SpecialPage
  */
 class SpecialMycontributions extends UnlistedSpecialPage {
index 3ae79f8..dc1e53c 100644 (file)
@@ -1,11 +1,13 @@
 <?php
 
+/** Constructor */
 function wfSpecialResetpass( $par ) {
        $form = new PasswordResetForm();
        $form->execute( $par );
 }
 
 /**
+ * Let users recover their password.
  * @addtogroup SpecialPage
  */
 class PasswordResetForm extends SpecialPage {
index cae34fe..408ac72 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * A special page looking for page without any category.
  * @addtogroup SpecialPage
  */
 class UncategorizedPagesPage extends PageQueryPage {
index 5437d2a..bd99caf 100644 (file)
@@ -8,7 +8,7 @@
  */
 
 /**
- *
+ * Constructor
  */
 function wfSpecialUndelete( $par ) {
     global $wgRequest;
@@ -18,7 +18,7 @@ function wfSpecialUndelete( $par ) {
 }
 
 /**
- * @todo document (just needs one-sentence top-level class description)
+ * Used to show archived pages and eventually restore them.
  * @addtogroup SpecialPage
  */
 class PageArchive {
index 9450d22..27af62e 100644 (file)
@@ -5,7 +5,7 @@
  */
 
 /**
- *
+ * You will need the extension MogileClient to use this special page.
  */
 require_once( 'MogileFS.php' );
 
@@ -19,6 +19,7 @@ function wfSpecialUploadMogile() {
 }
 
 /**
+ * Extends Special:Upload with MogileFS.
  * @addtogroup SpecialPage
  */
 class UploadFormMogile extends UploadForm {
index 0090604..9a451aa 100644 (file)
@@ -1,5 +1,7 @@
 <?php
-
+/**
+ * A collection of static methods to play with strings.
+ */
 class StringUtils {
        /**
         * Perform an operation equivalent to 
index e159152..9234319 100644 (file)
@@ -1,18 +1,20 @@
 <?php
-
-/* 
- * Allow programs to request this object from WebRequest::response() and handle all outputting (or lack of outputting) via it.
+/**
+ * Allow programs to request this object from WebRequest::response()
+ * and handle all outputting (or lack of outputting) via it.
  */
-
 class WebResponse {
+
+       /** Output a HTTP header */
        function header($string, $replace=true) {
                header($string,$replace);
        }
-       
+
+       /** Set the browser cookie */
        function setcookie($name, $value, $expire) {
                global $wgCookiePath, $wgCookieDomain, $wgCookieSecure;
                setcookie($name,$value,$expire, $wgCookiePath, $wgCookieDomain, $wgCookieSecure);
        }
 }
 
-?>
\ No newline at end of file
+?>