From: Nick Jenkins Date: Tue, 24 Apr 2007 06:53:31 +0000 (+0000) Subject: Doc tweaks: X-Git-Tag: 1.31.0-rc.0~53254 X-Git-Url: http://git.cyclocoop.org/%7B%24www_url%7Dadmin/compta/exercices/modifier.php?a=commitdiff_plain;h=bd23ec29c6f3d34b4ef45a8a70921660de2282aa;p=lhc%2Fweb%2Fwiklou.git Doc tweaks: * Seems like an opportune time to introduce "@addtogroup Media" documentation tags. * Merge "@addtogroup Metadata" (used by Exif.php) into "@addtogroup Media". * Few more moving comment blocks to above classes. --- diff --git a/includes/AjaxDispatcher.php b/includes/AjaxDispatcher.php index 90f68ecb31..ca12902919 100644 --- a/includes/AjaxDispatcher.php +++ b/includes/AjaxDispatcher.php @@ -11,7 +11,7 @@ if ( ! $wgUseAjax ) { require_once( 'AjaxFunctions.php' ); /** - * @todo Document - e.g. Provide top-level description of this class. + * Object-Oriented Ajax functions. * @addtogroup Ajax */ class AjaxDispatcher { diff --git a/includes/BagOStuff.php b/includes/BagOStuff.php index cc239369e2..2a04b9dddc 100644 --- a/includes/BagOStuff.php +++ b/includes/BagOStuff.php @@ -494,7 +494,6 @@ class TurckBagOStuff extends BagOStuff { * This is a wrapper for APC's shared memory functions * */ - class APCBagOStuff extends BagOStuff { function get($key) { $val = apc_fetch($key); @@ -553,6 +552,9 @@ class eAccelBagOStuff extends BagOStuff { } } +/** + * @todo document + */ class DBABagOStuff extends BagOStuff { var $mHandler, $mFile, $mReader, $mWriter, $mDisabled; diff --git a/includes/DjVuImage.php b/includes/DjVuImage.php index cd85147711..1e423565cd 100644 --- a/includes/DjVuImage.php +++ b/includes/DjVuImage.php @@ -28,6 +28,8 @@ * * File format docs are available in source package for DjVuLibre: * http://djvulibre.djvuzone.org/ + * + * @addtogroup Media */ class DjVuImage { function __construct( $filename ) { diff --git a/includes/Exif.php b/includes/Exif.php index f9de28a170..3a06ca1b91 100644 --- a/includes/Exif.php +++ b/includes/Exif.php @@ -1,6 +1,6 @@ * @copyright Copyright © 2005, Ævar Arnfjörð Bjarmason @@ -26,7 +26,7 @@ /** * @todo document (e.g. one-sentence class-overview description) - * @addtogroup Metadata + * @addtogroup Media */ class Exif { //@{ @@ -604,7 +604,7 @@ class Exif { /** * @todo document (e.g. one-sentence class-overview description) - * @addtogroup Metadata + * @addtogroup Media */ class FormatExif { /** diff --git a/includes/Feed.php b/includes/Feed.php index a77dcbced5..ed4343c31b 100644 --- a/includes/Feed.php +++ b/includes/Feed.php @@ -25,7 +25,7 @@ */ /** - * @todo document (needs one-sentence top-level class description + function descriptions). + * A base class for basic support for outputting syndication feeds in RSS and other formats. */ class FeedItem { /**#@+ diff --git a/includes/Image.php b/includes/Image.php index c09483edf6..ffe3802043 100644 --- a/includes/Image.php +++ b/includes/Image.php @@ -21,6 +21,8 @@ define( 'MW_IMAGE_VERSION', 1 ); * * Provides methods to retrieve paths (physical, logical, URL), * to generate thumbnails or for uploading. + * + * @addtogroup Media */ class Image { @@ -2003,6 +2005,10 @@ class Image } //class + +/** + * @addtogroup Media + */ class ArchivedFile { /** diff --git a/includes/ImageGallery.php b/includes/ImageGallery.php index 036d71783c..fba7714ce4 100644 --- a/includes/ImageGallery.php +++ b/includes/ImageGallery.php @@ -10,6 +10,7 @@ if ( ! defined( 'MEDIAWIKI' ) ) * * Add images to the gallery using add(), then render that list to HTML using toHTML(). * + * @addtogroup Media */ class ImageGallery { diff --git a/includes/ImagePage.php b/includes/ImagePage.php index 7d3414a8db..80375b92ee 100644 --- a/includes/ImagePage.php +++ b/includes/ImagePage.php @@ -10,6 +10,8 @@ if( !defined( 'MEDIAWIKI' ) ) /** * Special handling for image description pages + * + * @addtogroup Media */ class ImagePage extends Article { @@ -710,6 +712,7 @@ END /** * @todo document + * @addtogroup Media */ class ImageHistoryList { function ImageHistoryList( &$skin ) { diff --git a/includes/Linker.php b/includes/Linker.php index 190efebb54..e769ec0ffb 100644 --- a/includes/Linker.php +++ b/includes/Linker.php @@ -4,14 +4,12 @@ * These functions are used for primarily page content: * links, embedded images, table of contents. Links are * also used in the skin. - */ - -/** * For the moment, Skin is a descendent class of Linker. * In the future, it should probably be further split * so that ever other bit of the wiki doesn't have to * go loading up Skin to get at it. * + * @addtogroup Skins */ class Linker { function __construct() {} diff --git a/includes/MediaTransformOutput.php b/includes/MediaTransformOutput.php index 5004fcc9cc..60057e3ab0 100644 --- a/includes/MediaTransformOutput.php +++ b/includes/MediaTransformOutput.php @@ -2,6 +2,8 @@ /** * Base class for the output of MediaHandler::doTransform() and Image::transform(). + * + * @addtogroup Media */ abstract class MediaTransformOutput { /** @@ -63,6 +65,8 @@ abstract class MediaTransformOutput { /** * Media transform output for images + * + * @addtogroup Media */ class ThumbnailImage extends MediaTransformOutput { /** @@ -107,6 +111,8 @@ class ThumbnailImage extends MediaTransformOutput { /** * Basic media transform error class + * + * @addtogroup Media */ class MediaTransformError extends MediaTransformOutput { var $htmlMsg, $textMsg, $width, $height, $url, $path; @@ -146,6 +152,8 @@ class MediaTransformError extends MediaTransformOutput { /** * Shortcut class for parameter validation errors + * + * @addtogroup Media */ class TransformParameterError extends MediaTransformError { function __construct( $params ) { diff --git a/includes/MimeMagic.php b/includes/MimeMagic.php index df7a474936..db35535d9e 100644 --- a/includes/MimeMagic.php +++ b/includes/MimeMagic.php @@ -71,12 +71,13 @@ if ($wgLoadFileinfoExtension) { if(!extension_loaded('fileinfo')) dl('fileinfo.' . PHP_SHLIB_SUFFIX); } -/** Implements functions related to mime types such as detection and mapping to -* file extension, -* -* Instances of this class are stateles, there only needs to be one global instance -* of MimeMagic. Please use MimeMagic::singleton() to get that instance. -*/ +/** + * Implements functions related to mime types such as detection and mapping to + * file extension. + * + * Instances of this class are stateles, there only needs to be one global instance + * of MimeMagic. Please use MimeMagic::singleton() to get that instance. + */ class MimeMagic { /** diff --git a/includes/ProtectionForm.php b/includes/ProtectionForm.php index 4c4f2b3d14..3cafbd559c 100644 --- a/includes/ProtectionForm.php +++ b/includes/ProtectionForm.php @@ -17,12 +17,11 @@ * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html - * - * @addtogroup SpecialPage */ /** * @todo document, briefly. + * @addtogroup SpecialPage */ class ProtectionForm { var $mRestrictions = array(); diff --git a/includes/RawPage.php b/includes/RawPage.php index 2b2a5ce4f8..93484829a1 100644 --- a/includes/RawPage.php +++ b/includes/RawPage.php @@ -10,7 +10,8 @@ */ /** - * @todo document + * A simple method to retrieve the plain source of an article, + * using "action=raw" in the GET request string. */ class RawPage { var $mArticle, $mTitle, $mRequest; diff --git a/includes/SiteConfiguration.php b/includes/SiteConfiguration.php index 36c6aa85dc..0968460cc3 100644 --- a/includes/SiteConfiguration.php +++ b/includes/SiteConfiguration.php @@ -1,8 +1,4 @@ dbr->freeResult( $res ); return $contribs; } -}; +} /** * Special page "user contributions". diff --git a/includes/SpecialDoubleRedirects.php b/includes/SpecialDoubleRedirects.php index 2a7d1720a5..e7b355c586 100644 --- a/includes/SpecialDoubleRedirects.php +++ b/includes/SpecialDoubleRedirects.php @@ -6,7 +6,7 @@ /** * A special page listing redirects to redirecting page. - * The software will not procede double redirects automaticly to prevent loops. + * The software will automatically not follow double redirects, to prevent loops. * @addtogroup SpecialPage */ class DoubleRedirectsPage extends PageQueryPage { diff --git a/includes/SpecialEmailuser.php b/includes/SpecialEmailuser.php index b49812b582..900a2c328b 100644 --- a/includes/SpecialEmailuser.php +++ b/includes/SpecialEmailuser.php @@ -65,7 +65,7 @@ function wfSpecialEmailuser( $par ) { } /** - * @todo document + * Implements the Special:Emailuser web interface, and invokes userMailer for sending the email message. * @addtogroup SpecialPage */ class EmailUserForm { diff --git a/includes/User.php b/includes/User.php index d0c2db68a3..cfb665a268 100644 --- a/includes/User.php +++ b/includes/User.php @@ -24,7 +24,14 @@ class PasswordError extends MWException { } /** - * + * The User object encapsulates all of the user-specific settings (user_id, + * name, rights, password, email address, options, last login time). Client + * classes use the getXXX() functions to access these fields. These functions + * do all the work of determining whether the user is logged in, + * whether the requested option can be satisfied from cookies or + * whether a database query is needed. Most of the settings needed + * for rendering normal pages are set in the cookie to minimize use + * of the database. */ class User { diff --git a/includes/WebRequest.php b/includes/WebRequest.php index 1962ce9421..53273a22e1 100644 --- a/includes/WebRequest.php +++ b/includes/WebRequest.php @@ -140,7 +140,9 @@ class WebRequest { /** * Fetch a scalar from the input or return $default if it's not set. - * Returns a string. Arrays are discarded. + * Returns a string. Arrays are discarded. Useful for + * non-freeform text inputs (e.g. predefined internal text keys + * selected by a drop-down menu). For freeform input, see getText(). * * @param string $name * @param string $default optional default (or NULL) @@ -250,7 +252,9 @@ class WebRequest { * Fetch a text string from the given array or return $default if it's not * set. \r is stripped from the text, and with some language modules there * is an input transliteration applied. This should generally be used for - * form