From 85c84c27019e84bda96f27bafe47871662f72101 Mon Sep 17 00:00:00 2001 From: Antoine Musso Date: Tue, 10 Jul 2012 12:59:41 +0200 Subject: [PATCH] enhance DefaultSettings.php documentation This tweak our doxygen documentation for the DefaultSettings.php. Some paragraphs were simply reformatted, some received additions. To nicely render examples, I used the following snippet: @par Example: @code // some code there @endcode That replaces all the occurences. Replaced some notes and warnings with @note and @warning to output a nicely formatted box in our HTML documentation. Change-Id: Iea8d4e46eac2d971af43d47499d121d0c4e2bff3 --- includes/DefaultSettings.php | 906 ++++++++++++++++++++++------------- 1 file changed, 581 insertions(+), 325 deletions(-) diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php index c1c73d2b50..690d39ee29 100644 --- a/includes/DefaultSettings.php +++ b/includes/DefaultSettings.php @@ -1,6 +1,6 @@ + * @par Example: + * @code * $wgServer = 'http://example.com'; - * + * @endcode * * This is usually detected correctly by MediaWiki. If MediaWiki detects the * wrong server, it will redirect incorrectly after you save a page. In that @@ -273,11 +281,16 @@ $wgUploadStashScalerBaseUrl = false; /** * To set 'pretty' URL paths for actions other than - * plain page views, add to this array. For instance: + * plain page views, add to this array. + * + * @par Example: + * Set pretty URL for the edit action: + * @code * 'edit' => "$wgScriptPath/edit/$1" + * @endcode * - * There must be an appropriate script or rewrite rule - * in place to handle these URLs. + * There must be an appropriate script or rewrite rule in place to handle these + * URLs. */ $wgActionPaths = array(); @@ -300,7 +313,7 @@ $wgUploadStashMaxAge = 6 * 3600; // 6 hours $wgAllowImageMoving = true; /** - * These are additional characters that should be replaced with '-' in file names + * These are additional characters that should be replaced with '-' in filenames */ $wgIllegalFileChars = ":"; @@ -310,9 +323,10 @@ $wgIllegalFileChars = ":"; $wgFileStore = array(); /** - * What directory to place deleted uploads in + * What directory to place deleted uploads in. + * Defaults to "{$wgUploadDirectory}/deleted". */ -$wgDeletedDirectory = false; // Defaults to $wgUploadDirectory/deleted +$wgDeletedDirectory = false; /** * Set this to true if you use img_auth and want the user to see details on why access failed. @@ -418,10 +432,11 @@ $wgUseInstantCommons = false; * File backend structure configuration. * This is an array of file backend configuration arrays. * Each backend configuration has the following parameters: - * 'name' : A unique name for the backend - * 'class' : The file backend class to use - * 'wikiId' : A unique string that identifies the wiki (container prefix) - * 'lockManager' : The name of a lock manager (see $wgLockManagers) + * - 'name' : A unique name for the backend + * - 'class' : The file backend class to use + * - 'wikiId' : A unique string that identifies the wiki (container prefix) + * - 'lockManager' : The name of a lock manager (see $wgLockManagers) + * * Additional parameters are specific to the class used. */ $wgFileBackends = array(); @@ -429,8 +444,8 @@ $wgFileBackends = array(); /** * Array of configuration arrays for each lock manager. * Each backend configuration has the following parameters: - * 'name' : A unique name for the lock manger - * 'class' : The lock manger class to use + * - 'name' : A unique name for the lock manager + * - 'class' : The lock manger class to use * Additional parameters are specific to the class used. */ $wgLockManagers = array(); @@ -439,12 +454,13 @@ $wgLockManagers = array(); * Show EXIF data, on by default if available. * Requires PHP's EXIF extension: http://www.php.net/manual/en/ref.exif.php * - * NOTE FOR WINDOWS USERS: - * To enable EXIF functions, add the following lines to the - * "Windows extensions" section of php.ini: - * + * @note FOR WINDOWS USERS: + * To enable EXIF functions, add the following lines to the "Windows + * extensions" section of php.ini: + * @code{.ini} * extension=extensions/php_mbstring.dll * extension=extensions/php_exif.dll + * @endcode */ $wgShowEXIF = function_exists( 'exif_read_data' ); @@ -512,11 +528,13 @@ $wgCopyUploadsDomains = array(); * file and url keys. If the * key is set this value will be used as maximum * for non-specified types. * - * For example: + * @par Example: + * @code * $wgMaxUploadSize = array( * '*' => 250 * 1024, * 'url' => 500 * 1024, * ); + * @endcode * Sets the maximum for all uploads to 250 kB except for upload-by-url, which * will have a maximum of 500 kB. * @@ -526,8 +544,12 @@ $wgMaxUploadSize = 1024*1024*100; # 100MB /** * Point the upload navigation link to an external URL * Useful if you want to use a shared repository by default - * without disabling local uploads (use $wgEnableUploads = false for that) - * e.g. $wgUploadNavigationUrl = 'http://commons.wikimedia.org/wiki/Special:Upload'; + * without disabling local uploads (use $wgEnableUploads = false for that). + * + * @par Example: + * @code + * $wgUploadNavigationUrl = 'http://commons.wikimedia.org/wiki/Special:Upload'; + * @endcode */ $wgUploadNavigationUrl = false; @@ -539,14 +561,20 @@ $wgUploadNavigationUrl = false; $wgUploadMissingFileUrl = false; /** - * Give a path here to use thumb.php for thumbnail generation on client request, instead of - * generating them on render and outputting a static URL. This is necessary if some of your - * apache servers don't have read/write access to the thumbnail path. + * Give a path here to use thumb.php for thumbnail generation on client + * request, instead of generating them on render and outputting a static URL. + * This is necessary if some of your apache servers don't have read/write + * access to the thumbnail path. * - * Example: + * @par Example: + * @code * $wgThumbnailScriptPath = "{$wgScriptPath}/thumb{$wgScriptExtension}"; + * @endcode */ $wgThumbnailScriptPath = false; +/** + * @see $wgThumbnailScriptPath + */ $wgSharedThumbnailScriptPath = false; /** @@ -559,7 +587,8 @@ $wgSharedThumbnailScriptPath = false; * maintenance/rebuildImages.php to register them in the database. This is no * longer recommended, use maintenance/importImages.php instead. * - * Note that this variable may be ignored if $wgLocalFileRepo is set. + * @note That this variable may be ignored if $wgLocalFileRepo is set. + * @todo Deprecate the setting and ultimately remove it from Core. */ $wgHashedUploadDirectory = true; @@ -584,13 +613,17 @@ $wgRepositoryBaseUrl = "http://commons.wikimedia.org/wiki/File:"; * This is the list of preferred extensions for uploading files. Uploading files * with extensions not in this list will trigger a warning. * - * WARNING: If you add any OpenOffice or Microsoft Office file formats here, + * @warning If you add any OpenOffice or Microsoft Office file formats here, * such as odt or doc, and untrusted users are allowed to upload files, then * your wiki will be vulnerable to cross-site request forgery (CSRF). */ $wgFileExtensions = array( 'png', 'gif', 'jpg', 'jpeg' ); -/** Files with these extensions will never be allowed as uploads. */ +/** + * Files with these extensions will never be allowed as uploads. + * An array of file extensions to blacklist. You should append to this array + * if you want to blacklist additional files. + * */ $wgFileBlacklist = array( # HTML may contain cookie-stealing JavaScript and web bugs 'html', 'htm', 'js', 'jsb', 'mhtml', 'mht', 'xhtml', 'xht', @@ -628,7 +661,7 @@ $wgAllowJavaUploads = false; /** * This is a flag to determine whether or not to check file extensions on upload. * - * WARNING: setting this to false is insecure for public wikis. + * @warning Setting this to false is insecure for public wikis. */ $wgCheckFileExtensions = true; @@ -636,18 +669,21 @@ $wgCheckFileExtensions = true; * If this is turned off, users may override the warning for files not covered * by $wgFileExtensions. * - * WARNING: setting this to false is insecure for public wikis. + * @warning Setting this to false is insecure for public wikis. */ $wgStrictFileExtensions = true; /** * Setting this to true will disable the upload system's checks for HTML/JavaScript. - * THIS IS VERY DANGEROUS on a publicly editable site, so USE wgGroupPermissions - * TO RESTRICT UPLOADING to only those that you trust + * + * @warning THIS IS VERY DANGEROUS on a publicly editable site, so USE + * $wgGroupPermissions TO RESTRICT UPLOADING to only those that you trust */ $wgDisableUploadScriptChecks = false; -/** Warn if uploaded files are larger than this (in bytes), or false to disable*/ +/** + * Warn if uploaded files are larger than this (in bytes), or false to disable + */ $wgUploadSizeWarning = false; /** @@ -674,18 +710,18 @@ $wgTrustedMediaFormats = array( * Each entry in the array maps a MIME type to a class name */ $wgMediaHandlers = array( - 'image/jpeg' => 'JpegHandler', - 'image/png' => 'PNGHandler', - 'image/gif' => 'GIFHandler', - 'image/tiff' => 'TiffHandler', + 'image/jpeg' => 'JpegHandler', + 'image/png' => 'PNGHandler', + 'image/gif' => 'GIFHandler', + 'image/tiff' => 'TiffHandler', 'image/x-ms-bmp' => 'BmpHandler', - 'image/x-bmp' => 'BmpHandler', - 'image/x-xcf' => 'XCFHandler', - 'image/svg+xml' => 'SvgHandler', // official - 'image/svg' => 'SvgHandler', // compat + 'image/x-bmp' => 'BmpHandler', + 'image/x-xcf' => 'XCFHandler', + 'image/svg+xml' => 'SvgHandler', // official + 'image/svg' => 'SvgHandler', // compat 'image/vnd.djvu' => 'DjVuHandler', // official - 'image/x.djvu' => 'DjVuHandler', // compat - 'image/x-djvu' => 'DjVuHandler', // compat + 'image/x.djvu' => 'DjVuHandler', // compat + 'image/x-djvu' => 'DjVuHandler', // compat ); /** @@ -719,17 +755,18 @@ $wgImageMagickTempDir = false; * %s will be replaced with the source path, %d with the destination * %w and %h will be replaced with the width and height. * - * Example for GraphicMagick: - * + * @par Example for GraphicMagick: + * @code * $wgCustomConvertCommand = "gm convert %s -resize %wx%h %d" - * + * @endcode * * Leave as false to skip this. */ $wgCustomConvertCommand = false; /** - * Some tests and extensions use exiv2 to manipulate the EXIF metadata in some image formats. + * Some tests and extensions use exiv2 to manipulate the EXIF metadata in some + * image formats. */ $wgExiv2Command = '/usr/bin/exiv2'; @@ -767,11 +804,15 @@ $wgSVGMaxSize = 2048; $wgSVGMetadataCutoff = 262144; /** - * MediaWiki will reject HTMLesque tags in uploaded files due to idiotic browsers which can't - * perform basic stuff like MIME detection and which are vulnerable to further idiots uploading - * crap files as images. When this directive is on, "" will be allowed in files with - * an "image/svg+xml" MIME type. You should leave this disabled if your web server is misconfigured - * and doesn't send appropriate MIME types for SVG images. + * Disallow <title> element in SVG files. + * + * MediaWiki will reject HTMLesque tags in uploaded files due to idiotic + * browsers which can not perform basic stuff like MIME detection and which are + * vulnerable to further idiots uploading crap files as images. + * + * When this directive is on, "<title>" will be allowed in files with an + * "image/svg+xml" MIME type. You should leave this disabled if your web server + * is misconfigured and doesn't send appropriate MIME types for SVG images. */ $wgAllowTitlesInSVG = false; @@ -801,13 +842,13 @@ $wgMaxAnimatedGifArea = 1.25e7; * For inline display, we need to convert to PNG or JPEG. * Note scaling should work with ImageMagick, but may not with GD scaling. * - * Example: - * <code> + * @par Example: + * @code * // PNG is lossless, but inefficient for photos * $wgTiffThumbnailType = array( 'png', 'image/png' ); * // JPEG is good for photos, but has no transparency support. Bad for diagrams. * $wgTiffThumbnailType = array( 'jpg', 'image/jpeg' ); - * </code> + * @endcode */ $wgTiffThumbnailType = false; @@ -941,10 +982,11 @@ $wgLoadFileinfoExtension = false; * the mime type to standard output. * The name of the file to process will be appended to the command given here. * If not set or NULL, mime_content_type will be used if available. - * Example: - * <code> + * + * @par Example: + * @code * #$wgMimeDetectorCommand = "file -bi"; # use external mime detector (Linux) - * </code> + * @endcode */ $wgMimeDetectorCommand = null; @@ -1021,7 +1063,10 @@ $wgThumbUpright = 0.75; $wgDirectoryMode = 0777; /** - * DJVU settings + * @name DJVU settings + * @{ + */ +/** * Path of the djvudump executable * Enable this and $wgDjvuRenderer to enable djvu rendering */ @@ -1046,15 +1091,18 @@ $wgDjvuTxt = null; * Path of the djvutoxml executable * This works like djvudump except much, much slower as of version 3.5. * - * For now I recommend you use djvudump instead. The djvuxml output is + * For now we recommend you use djvudump instead. The djvuxml output is * probably more stable, so we'll switch back to it as soon as they fix * the efficiency problem. * http://sourceforge.net/tracker/index.php?func=detail&aid=1704049&group_id=32953&atid=406583 + * + * @par Example: + * @code + * $wgDjvuToXML = 'djvutoxml'; + * @endcode */ -# $wgDjvuToXML = 'djvutoxml'; $wgDjvuToXML = null; - /** * Shell command for the DJVU post processor * Default: pnmtopng, since ddjvu generates ppm output @@ -1065,6 +1113,7 @@ $wgDjvuPostProcessor = 'pnmtojpeg'; * File extension for the DJVU post processor output */ $wgDjvuOutputExtension = 'jpg'; +/** @} */ # end of DJvu } /** @} */ # end of file uploads } @@ -1141,17 +1190,21 @@ $wgNewPasswordExpiry = 3600 * 24 * 7; $wgUserEmailConfirmationTokenExpiry = 7 * 24 * 60 * 60; /** - * SMTP Mode + * SMTP Mode. + * * For using a direct (authenticated) SMTP server connection. * Default to false or fill an array : - * <code> - * "host" => 'SMTP domain', - * "IDHost" => 'domain for MessageID', - * "port" => "25", - * "auth" => true/false, - * "username" => user, - * "password" => password - * </code> + * + * @code + * $wgSMTP = array( + * 'host' => 'SMTP domain', + * 'IDHost' => 'domain for MessageID', + * 'port' => '25', + * 'auth' => [true|false], + * 'username' => [SMTP username], + * 'password' => [SMTP password], + * ); + * @endcode */ $wgSMTP = false; @@ -1173,9 +1226,9 @@ $wgEnotifFromEditor = false; # It call this to be a "user-preferences-option (UPO)" /** - * Require email authentication before sending mail to an email addres. This is - * highly recommended. It prevents MediaWiki from being used as an open spam - * relay. + * Require email authentication before sending mail to an email address. + * This is highly recommended. It prevents MediaWiki from being used as an open + * spam relay. */ $wgEmailAuthentication = true; @@ -1354,9 +1407,9 @@ $wgSharedTables = array( 'user', 'user_properties' ); * accidental misconfiguration or MediaWiki bugs, set read_only=1 on all your * slaves in my.cnf. You can set read_only mode at runtime using: * - * <code> + * @code * SET @@read_only=1; - * </code> + * @endcode * * Since the effect of writing to a slave is so damaging and difficult to clean * up, we at Wikimedia set read_only=1 in my.cnf on all our DB servers, even @@ -1391,8 +1444,9 @@ $wgDBerrorLogInUTC = false; $wgDBClusterTimeout = 10; /** - * Scale load balancer polling time so that under overload conditions, the database server - * receives a SHOW STATUS query at an average interval of this many microseconds + * Scale load balancer polling time so that under overload conditions, the + * database server receives a SHOW STATUS query at an average interval of this + * many microseconds */ $wgDBAvgStatusPoll = 2000; @@ -1400,7 +1454,7 @@ $wgDBAvgStatusPoll = 2000; * Set to true to engage MySQL 4.1/5.0 charset-related features; * for now will just cause sending of 'SET NAMES=utf8' on connect. * - * WARNING: THIS IS EXPERIMENTAL! + * @warning THIS IS EXPERIMENTAL! * * May break if you're not using the table defs from mysql5/tables.sql. * May break if you're upgrading an existing wiki if set differently. @@ -1453,19 +1507,30 @@ $wgCompressRevisions = false; /** * External stores allow including content - * from non database sources following URL links + * from non database sources following URL links. * * Short names of ExternalStore classes may be specified in an array here: + * @code * $wgExternalStores = array("http","file","custom")... + * @endcode * * CAUTION: Access to database might lead to code execution */ $wgExternalStores = false; /** - * An array of external mysql servers, e.g. - * $wgExternalServers = array( 'cluster1' => array( 'srv28', 'srv29', 'srv30' ) ); - * Used by LBFactory_Simple, may be ignored if $wgLBFactoryConf is set to another class. + * An array of external MySQL servers. + * + * @par Example: + * Create a cluster named 'cluster1' containing three servers: + * @code + * $wgExternalServers = array( + * 'cluster1' => array( 'srv28', 'srv29', 'srv30' ) + * ); + * @endcode + * + * Used by LBFactory_Simple, may be ignored if $wgLBFactoryConf is set to + * another class. */ $wgExternalServers = array(); @@ -1474,9 +1539,12 @@ $wgExternalServers = array(); * Part of a URL, e.g. DB://cluster1 * * Can be an array instead of a single string, to enable data distribution. Keys - * must be consecutive integers, starting at zero. Example: + * must be consecutive integers, starting at zero. * + * @par Example: + * @code * $wgDefaultExternalStore = array( 'DB://cluster1', 'DB://cluster2' ); + * @endcode * * @var array */ @@ -1639,8 +1707,8 @@ $wgObjectCaches = array( ); /** - * The expiry time for the parser cache, in seconds. The default is 86.4k - * seconds, otherwise known as a day. + * The expiry time for the parser cache, in seconds. + * The default is 86400 (one day). */ $wgParserCacheExpireTime = 86400; @@ -1689,9 +1757,9 @@ $wgMemCachedTimeout = 100000; $wgUseLocalMessageCache = false; /** - * Defines format of local cache - * true - Serialized object - * false - PHP source file (Warning - security risk) + * Defines format of local cache. + * - true: Serialized object + * - false: PHP source file (Warning - security risk) */ $wgLocalMessageCacheSerialized = true; @@ -1704,23 +1772,23 @@ $wgAdaptiveMessageCache = false; /** * Localisation cache configuration. Associative array with keys: - * class: The class to use. May be overridden by extensions. + * class: The class to use. May be overridden by extensions. * - * store: The location to store cache data. May be 'files', 'db' or - * 'detect'. If set to "files", data will be in CDB files. If set - * to "db", data will be stored to the database. If set to - * "detect", files will be used if $wgCacheDirectory is set, - * otherwise the database will be used. + * store: The location to store cache data. May be 'files', 'db' or + * 'detect'. If set to "files", data will be in CDB files. If set + * to "db", data will be stored to the database. If set to + * "detect", files will be used if $wgCacheDirectory is set, + * otherwise the database will be used. * - * storeClass: The class name for the underlying storage. If set to a class - * name, it overrides the "store" setting. + * storeClass: The class name for the underlying storage. If set to a class + * name, it overrides the "store" setting. * - * storeDirectory: If the store class puts its data in files, this is the - * directory it will use. If this is false, $wgCacheDirectory - * will be used. + * storeDirectory: If the store class puts its data in files, this is the + * directory it will use. If this is false, $wgCacheDirectory + * will be used. * - * manualRecache: Set this to true to disable cache updates on web requests. - * Use maintenance/rebuildLocalisationCache.php instead. + * manualRecache: Set this to true to disable cache updates on web requests. + * Use maintenance/rebuildLocalisationCache.php instead. */ $wgLocalisationCacheConf = array( 'class' => 'LocalisationCache', @@ -1735,14 +1803,17 @@ $wgCachePages = true; /** * Set this to current time to invalidate all prior cached pages. Affects both - * client- and server-side caching. + * client-side and server-side caching. * You can get the current date on your server by using the command: + * @verbatim * date +%Y%m%d%H%M%S + * @endverbatim */ $wgCacheEpoch = '20030516000000'; /** * Bump this number when changing the global style sheets and JavaScript. + * * It should be appended in the query string of static CSS and JS includes, * to ensure that client-side caches do not keep obsolete copies of global * styles. @@ -1868,10 +1939,12 @@ $wgUseXVO = false; $wgVaryOnXFP = false; /** - * Internal server name as known to Squid, if different. Example: - * <code> + * Internal server name as known to Squid, if different. + * + * @par Example: + * @code * $wgInternalServer = 'http://yourinternal.tld:8000'; - * </code> + * @endcode */ $wgInternalServer = false; @@ -1919,6 +1992,7 @@ $wgMaxSquidPurgeTitles = 400; * * Example configuration to send purges for upload.wikimedia.org to one * multicast group and all other purges to another: + * @code * $wgHTCPMulticastRouting = array( * '|^https?://upload\.wikimedia\.org|' => array( * 'host' => '239.128.0.113', @@ -1929,6 +2003,7 @@ $wgMaxSquidPurgeTitles = 400; * 'port' => 4827, * ), * ); + * @endcode * * @see $wgHTCPMulticastTTL */ @@ -1977,11 +2052,12 @@ $wgLanguageCode = 'en'; /** * Some languages need different word forms, usually for different cases. - * Used in Language::convertGrammar(). Example: + * Used in Language::convertGrammar(). * - * <code> + * @par Example: + * @code * $wgGrammarForms['en']['genitive']['car'] = 'car\'s'; - * </code> + * @endcode */ $wgGrammarForms = array(); @@ -2064,7 +2140,7 @@ $wgAllUnicodeFixes = false; * converting a wiki from MediaWiki 1.4 or earlier to UTF-8 without the * burdensome mass conversion of old text data. * - * NOTE! This DOES NOT touch any fields other than old_text.Titles, comments, + * @note This DOES NOT touch any fields other than old_text. Titles, comments, * user names, etc still must be converted en masse in the database before * continuing as a UTF-8 wiki. */ @@ -2173,28 +2249,27 @@ $wgCanonicalLanguageLinks = true; $wgDefaultLanguageVariant = false; /** - * Disabled variants array of language variant conversion. Example: - * <code> + * Disabled variants array of language variant conversion. + * + * @par Example: + * @code * $wgDisabledVariants[] = 'zh-mo'; * $wgDisabledVariants[] = 'zh-my'; - * </code> - * - * or: - * - * <code> - * $wgDisabledVariants = array('zh-mo', 'zh-my'); - * </code> + * @endcode */ $wgDisabledVariants = array(); /** * Like $wgArticlePath, but on multi-variant wikis, this provides a * path format that describes which parts of the URL contain the - * language variant. For Example: + * language variant. * - * $wgLanguageCode = 'sr'; - * $wgVariantArticlePath = '/$2/$1'; - * $wgArticlePath = '/wiki/$1'; + * @par Example: + * @code + * $wgLanguageCode = 'sr'; + * $wgVariantArticlePath = '/$2/$1'; + * $wgArticlePath = '/wiki/$1'; + * @endcode * * A link to /wiki/ would be redirected to /sr/Главна_страна * @@ -2220,10 +2295,14 @@ $wgLoginLanguageSelector = false; * wfMsg(). The code behaves this way by default. However, sites like the * Wikimedia Commons do offer different versions of 'mainpage' and the like for * different languages. This array provides a way to override the default - * behavior. For example, to allow language-specific main page and community - * portal, set + * behavior. * - * $wgForceUIMsgAsContentMsg = array( 'mainpage', 'portal-url' ); + * @par Example: + * To allow language-specific main page and community + * portal: + * @code + * $wgForceUIMsgAsContentMsg = array( 'mainpage', 'portal-url' ); + * @endcode */ $wgForceUIMsgAsContentMsg = array(); @@ -2238,13 +2317,13 @@ $wgForceUIMsgAsContentMsg = array(); * Timezones can be translated by editing MediaWiki messages of type * timezone-nameinlowercase like timezone-utc. * - * Examples: - * <code> + * @par Examples: + * @code * $wgLocaltimezone = 'GMT'; * $wgLocaltimezone = 'PST8PDT'; * $wgLocaltimezone = 'Europe/Sweden'; * $wgLocaltimezone = 'CET'; - * </code> + * @endcode */ $wgLocaltimezone = null; @@ -2265,7 +2344,7 @@ $wgLocalTZoffset = null; * language variant conversion is disabled in interface messages. Setting this * to true re-enables it. * - * This variable should be removed (implicitly false) in 1.20 or earlier. + * @todo This variable should be removed (implicitly false) in 1.20 or earlier. */ $wgBug34832TransitionalRollback = true; @@ -2362,9 +2441,13 @@ $wgWellFormedXml = true; /** * Permit other namespaces in addition to the w3.org default. - * Use the prefix for the key and the namespace for the value. For - * example: + * + * Use the prefix for the key and the namespace for the value. + * + * @par Example: + * @code * $wgXhtmlNamespaces['svg'] = 'http://www.w3.org/2000/svg'; + * @endCode * Normally we wouldn't have to define this in the root "<html>" * element, but IE needs it there in some circumstances. * @@ -2376,7 +2459,7 @@ $wgXhtmlNamespaces = array(); /** * Show IP address, for non-logged in users. It's necessary to switch this off * for some forms of caching. - * Will disable file cache. + * @warning Will disable file cache. */ $wgShowIPinHeader = true; @@ -2535,15 +2618,16 @@ $wgExperimentalHtmlIds = false; * The value should be either a string or an array. If it is a string it will be output * directly as html, however some skins may choose to ignore it. An array is the preferred format * for the icon, the following keys are used: - * src: An absolute url to the image to use for the icon, this is recommended + * - src: An absolute url to the image to use for the icon, this is recommended * but not required, however some skins will ignore icons without an image - * url: The url to use in the <a> arround the text or icon, if not set an <a> will not be outputted - * alt: This is the text form of the icon, it will be displayed without an image in + * - url: The url to use in the a element arround the text or icon, if not set an a element will not be outputted + * - alt: This is the text form of the icon, it will be displayed without an image in * skins like Modern or if src is not set, and will otherwise be used as * the alt="" for the image. This key is required. - * width and height: If the icon specified by src is not of the standard size + * - width and height: If the icon specified by src is not of the standard size * you can specify the size of image to use with these keys. * Otherwise they will default to the standard 88x31. + * @todo Reformat documentation. */ $wgFooterIcons = array( "copyright" => array( @@ -2559,23 +2643,24 @@ $wgFooterIcons = array( ); /** - * Login / create account link behavior when it's possible for anonymous users to create an account - * true = use a combined login / create account link - * false = split login and create account into two separate links + * Login / create account link behavior when it's possible for anonymous users + * to create an account. + * - true = use a combined login / create account link + * - false = split login and create account into two separate links */ $wgUseCombinedLoginLink = true; /** - * Search form behavior for Vector skin only - * true = use an icon search button - * false = use Go & Search buttons + * Search form behavior for Vector skin only. + * - true = use an icon search button + * - false = use Go & Search buttons */ $wgVectorUseSimpleSearch = false; /** - * Watch and unwatch as an icon rather than a link for Vector skin only - * true = use an icon watch/unwatch button - * false = use watch/unwatch text link + * Watch and unwatch as an icon rather than a link for Vector skin only. + * - true = use an icon watch/unwatch button + * - false = use watch/unwatch text link */ $wgVectorUseIconWatch = false; @@ -2613,10 +2698,13 @@ $wgSend404Code = true; */ /** - * Client-side resource modules. Extensions should add their module definitions - * here. + * Client-side resource modules. + * + * Extensions should add their resource loader module definitions + * to the $wgResourceModules variable. * - * Example: + * @par Example: + * @code * $wgResourceModules['ext.myExtension'] = array( * 'scripts' => 'myExtension.js', * 'styles' => 'myExtension.css', @@ -2624,6 +2712,7 @@ $wgSend404Code = true; * 'localBasePath' => dirname( __FILE__ ), * 'remoteExtPath' => 'MyExtension', * ); + * @endcode */ $wgResourceModules = array(); @@ -2632,11 +2721,13 @@ $wgResourceModules = array(); * built-in source that is not in this array, but defined by * ResourceLoader::__construct() so that it cannot be unset. * - * Example: + * @par Example: + * @code * $wgResourceLoaderSources['foo'] = array( * 'loadScript' => 'http://example.org/w/load.php', * 'apiScript' => 'http://example.org/w/api.php' * ); + * @endcode */ $wgResourceLoaderSources = array(); @@ -2647,7 +2738,9 @@ $wgResourceLoaderSources = array(); $wgResourceBasePath = null; /** - * Maximum time in seconds to cache resources served by the resource loader + * Maximum time in seconds to cache resources served by the resource loader. + * + * @todo Document array structure */ $wgResourceLoaderMaxage = array( 'versioned' => array( @@ -2663,8 +2756,9 @@ $wgResourceLoaderMaxage = array( ); /** - * The default debug mode (on/off) for of ResourceLoader requests. This will still - * be overridden when the debug URL parameter is used. + * The default debug mode (on/off) for of ResourceLoader requests. + * + * This will still be overridden when the debug URL parameter is used. */ $wgResourceLoaderDebug = false; @@ -2690,33 +2784,54 @@ $wgResourceLoaderMinifierMaxLineLength = 1000; /** * Whether to include the mediawiki.legacy JS library (old wikibits.js), and its - * dependencies + * dependencies. */ $wgIncludeLegacyJavaScript = true; /** - * Whether to preload the mediawiki.util module as blocking module in the top queue. - * Before MediaWiki 1.19, modules used to load slower/less asynchronous which allowed - * modules to lack dependencies on 'popular' modules that were likely loaded already. + * Whether to preload the mediawiki.util module as blocking module in the top + * queue. + * + * Before MediaWiki 1.19, modules used to load slower/less asynchronous which + * allowed modules to lack dependencies on 'popular' modules that were likely + * loaded already. + * * This setting is to aid scripts during migration by providing mediawiki.util * unconditionally (which was the most commonly missed dependency). - * It doesn't cover all missing dependencies obviously but should fix most of them. + * It doesn't cover all missing dependencies obviously but should fix most of + * them. + * * This should be removed at some point after site/user scripts have been fixed. - * Enable this if your wiki has a large amount of user/site scripts that are lacking - * dependencies. + * Enable this if your wiki has a large amount of user/site scripts that are + * lacking dependencies. + * @todo Deprecate */ $wgPreloadJavaScriptMwUtil = false; /** - * Whether or not to assing configuration variables to the global window object. - * If this is set to false, old code using deprecated variables like: - * " if ( window.wgRestrictionEdit ) ..." + * Whether or not to assign configuration variables to the global window object. + * + * If this is set to false, old code using deprecated variables will no longer + * work. + * + * @par Example of legacy code: + * @code{,js} + * if ( window.wgRestrictionEdit ) { ... } + * @endcode + * or: + * @code{,js} + * if ( wgIsArticle ) { ... } + * @endcode + * + * Instead, one needs to use mw.config. + * @par Example using mw.config global configuration: + * @code{,js} + * if ( mw.config.exists('wgRestrictionEdit') ) { ... } + * @endcode * or: - * " if ( wgIsArticle ) ..." - * will no longer work and needs to use mw.config instead. For example: - * " if ( mw.config.exists('wgRestrictionEdit') )" - * or - * " if ( mw.config.get('wgIsArticle') )". + * @code{,js} + * if ( mw.config.get('wgIsArticle') ) { ... } + * @endcode */ $wgLegacyJavaScriptGlobals = true; @@ -2734,8 +2849,8 @@ $wgLegacyJavaScriptGlobals = true; $wgResourceLoaderMaxQueryLength = -1; /** - * If set to true, JavaScript modules loaded from wiki pages will be parsed prior - * to minification to validate it. + * If set to true, JavaScript modules loaded from wiki pages will be parsed + * prior to minification to validate it. * * Parse errors will result in a JS exception being thrown during module load, * which avoids breaking other modules loaded in the same request. @@ -2789,19 +2904,25 @@ $wgMetaNamespaceTalk = false; * names of existing namespaces. Extensions developers should use * $wgCanonicalNamespaceNames. * - * PLEASE NOTE: Once you delete a namespace, the pages in that namespace will + * @warning Once you delete a namespace, the pages in that namespace will * no longer be accessible. If you rename it, then you can access them through * the new namespace name. * * Custom namespaces should start at 100 to avoid conflicting with standard * namespaces, and should always follow the even/odd main/talk pattern. + * + * @par Example: + * @code + * $wgExtraNamespaces = array( + * 100 => "Hilfe", + * 101 => "Hilfe_Diskussion", + * 102 => "Aide", + * 103 => "Discussion_Aide" + * ); + * @endcode + * + * @todo Add a note about maintenance/namespaceDupes.php */ -# $wgExtraNamespaces = array( -# 100 => "Hilfe", -# 101 => "Hilfe_Diskussion", -# 102 => "Aide", -# 103 => "Discussion_Aide" -# ); $wgExtraNamespaces = array(); /** @@ -2813,18 +2934,22 @@ $wgExtraNamespaces = array(); $wgExtraGenderNamespaces = array(); /** - * Namespace aliases + * Namespace aliases. + * * These are alternate names for the primary localised namespace names, which * are defined by $wgExtraNamespaces and the language file. If a page is * requested with such a prefix, the request will be redirected to the primary * name. * * Set this to a map from namespace names to IDs. - * Example: + * + * @par Example: + * @code * $wgNamespaceAliases = array( * 'Wikipedian' => NS_USER, * 'Help' => 100, * ); + * @endcode */ $wgNamespaceAliases = array(); @@ -2839,8 +2964,8 @@ $wgNamespaceAliases = array(); * - + Enabled by default, but doesn't work with path to query rewrite rules, corrupted by apache * - ? Enabled by default, but doesn't work with path to PATH_INFO rewrites * - * All three of these punctuation problems can be avoided by using an alias, instead of a - * rewrite rule of either variety. + * All three of these punctuation problems can be avoided by using an alias, + * instead of a rewrite rule of either variety. * * The problem with % is that when using a path to query rewrite rule, URLs are * double-unescaped: once by Apache's path conversion code, and again by PHP. So @@ -2866,33 +2991,47 @@ $wgLocalInterwiki = false; */ $wgInterwikiExpiry = 10800; -/** Interwiki caching settings. - $wgInterwikiCache specifies path to constant database file - This cdb database is generated by dumpInterwiki from maintenance - and has such key formats: - dbname:key - a simple key (e.g. enwiki:meta) - _sitename:key - site-scope key (e.g. wiktionary:meta) - __global:key - global-scope key (e.g. __global:meta) - __sites:dbname - site mapping (e.g. __sites:enwiki) - Sites mapping just specifies site name, other keys provide - "local url" data layout. - $wgInterwikiScopes specify number of domains to check for messages: - 1 - Just wiki(db)-level - 2 - wiki and global levels - 3 - site levels - $wgInterwikiFallbackSite - if unable to resolve from cache +/** + * @name Interwiki caching settings. + * @{ + */ +/** + *$wgInterwikiCache specifies path to constant database file. + * + * This cdb database is generated by dumpInterwiki from maintenance and has + * such key formats: + * - dbname:key - a simple key (e.g. enwiki:meta) + * - _sitename:key - site-scope key (e.g. wiktionary:meta) + * - __global:key - global-scope key (e.g. __global:meta) + * - __sites:dbname - site mapping (e.g. __sites:enwiki) + * + * Sites mapping just specifies site name, other keys provide "local url" + * data layout. */ $wgInterwikiCache = false; +/** + * Specify number of domains to check for messages. + * - 1: Just wiki(db)-level + * - 2: wiki and global levels + * - 3: site levels + */ $wgInterwikiScopes = 3; +/** + * $wgInterwikiFallbackSite - if unable to resolve from cache + */ $wgInterwikiFallbackSite = 'wiki'; +/** @} */ # end of Interwiki caching settings. /** * If local interwikis are set up which allow redirects, * set this regexp to restrict URLs which will be displayed * as 'redirected from' links. * + * @par Example: * It might look something like this: + * @code * $wgRedirectSources = '!^https?://[a-z-]+\.wikipedia\.org/!'; + * @endcode * * Leave at false to avoid displaying any incoming redirect markers. * This does not affect intra-wiki redirects, which don't change @@ -2902,7 +3041,8 @@ $wgRedirectSources = false; /** * Set this to false to avoid forcing the first letter of links to capitals. - * WARNING: may break links! This makes links COMPLETELY case-sensitive. Links + * + * @warning may break links! This makes links COMPLETELY case-sensitive. Links * appearing with a capital at the beginning of a sentence will *not* go to the * same place as links in the middle of a sentence using a lowercase initial. */ @@ -2916,7 +3056,11 @@ $wgCapitalLinks = true; * associated content namespaces, the values for those are ignored in favor of the * subject namespace's setting. Setting for NS_MEDIA is taken automatically from * NS_FILE. - * EX: $wgCapitalLinkOverrides[ NS_FILE ] = false; + * + * @par Example: + * @code + * $wgCapitalLinkOverrides[ NS_FILE ] = false; + * @endcode */ $wgCapitalLinkOverrides = array(); @@ -3049,11 +3193,11 @@ $wgAllowExternalImages = false; * You can use this to set up a trusted, simple repository of images. * You may also specify an array of strings to allow multiple sites * - * Examples: - * <code> + * @par Examples: + * @code * $wgAllowExternalImagesFrom = 'http://127.0.0.1/'; * $wgAllowExternalImagesFrom = array( 'http://127.0.0.1/', 'http://example.com' ); - * </code> + * @endcode */ $wgAllowExternalImagesFrom = ''; @@ -3500,18 +3644,19 @@ $wgBlockCIDRLimit = array( $wgBlockDisablesLogin = false; /** - * Pages anonymous user may see as an array, e.g. + * Pages anonymous user may see, set as an array of pages titles. * - * <code> + * @par Example: + * @code * $wgWhitelistRead = array ( "Main Page", "Wikipedia:Help"); - * </code> + * @endcode * * Special:Userlogin and Special:ChangePassword are always whitelisted. * - * NOTE: This will only work if $wgGroupPermissions['*']['read'] is false -- + * @note This will only work if $wgGroupPermissions['*']['read'] is false -- * see below. Otherwise, ALL pages are accessible, regardless of this setting. * - * Also note that this will only protect _pages in the wiki_. Uploaded files + * @note Also that this will only protect _pages in the wiki_. Uploaded files * will remain readable. You can use img_auth.php to protect uploaded files, * see http://www.mediawiki.org/wiki/Manual:Image_Authorization */ @@ -3525,6 +3670,7 @@ $wgEmailConfirmToEdit = false; /** * Permission keys given to users in each group. + * * This is an array where the keys are all groups and each value is an * array of the format (right => boolean). * @@ -3655,6 +3801,7 @@ $wgGroupPermissions['bureaucrat']['noratelimit'] = true; /** * Permission keys revoked from users in each group. + * * This acts the same way as wgGroupPermissions above, except that * if the user is in a group here, the permission will be removed from them. * @@ -3672,16 +3819,20 @@ $wgImplicitGroups = array( '*', 'user', 'autoconfirmed' ); * A map of group names that the user is in, to group names that those users * are allowed to add or revoke. * - * Setting the list of groups to add or revoke to true is equivalent to "any group". - * - * For example, to allow sysops to add themselves to the "bot" group: + * Setting the list of groups to add or revoke to true is equivalent to "any + * group". * + * @par Example: + * To allow sysops to add themselves to the "bot" group: + * @code * $wgGroupsAddToSelf = array( 'sysop' => array( 'bot' ) ); + * @endcode * + * @par Example: * Implicit groups may be used for the source group, for instance: - * + * @code * $wgGroupsRemoveFromSelf = array( '*' => true ); - * + * @endcode * This allows users in the '*' group (i.e. any user) to remove themselves from * any group that they happen to be in. * @@ -3717,13 +3868,16 @@ $wgRestrictionLevels = array( '', 'autoconfirmed', 'sysop' ); * namespace. If you list more than one permission, a user must * have all of them to edit pages in that namespace. * - * Note: NS_MEDIAWIKI is implicitly restricted to editinterface. + * @note NS_MEDIAWIKI is implicitly restricted to 'editinterface'. */ $wgNamespaceProtection = array(); /** * Pages in namespaces in this array can not be used as templates. - * Elements must be numeric namespace ids. + * + * Elements MUST be numeric namespace ids, you can safely use the MediaWiki + * namespaces constants (NS_USER, NS_MAIN...). + * * Among other things, this may be useful to enforce read-restrictions * which may otherwise be bypassed by using the template machanism. */ @@ -3739,11 +3893,15 @@ $wgNonincludableNamespaces = array(); * * When left at 0, all registered accounts will pass. * - * Example: - * <code> + * @par Example: + * Set automatic confirmation to 10 minutes (which is 600 seconds): + * @code * $wgAutoConfirmAge = 600; // ten minutes + * @endcode + * Set age to one day: + * @code * $wgAutoConfirmAge = 3600*24; // one day - * </code> + * @endcode */ $wgAutoConfirmAge = 0; @@ -3751,14 +3909,18 @@ $wgAutoConfirmAge = 0; * Number of edits an account requires before it is autoconfirmed. * Passing both this AND the time requirement is needed. Example: * - * <code> + * @par Example: + * @code * $wgAutoConfirmCount = 50; - * </code> + * @endcode */ $wgAutoConfirmCount = 0; /** * Automatically add a usergroup to any user who matches certain conditions. + * + * @todo Redocument $wgAutopromote + * * The format is * array( '&' or '|' or '^' or '!', cond1, cond2, ... ) * where cond1, cond2, ... are themselves conditions; *OR* @@ -3786,14 +3948,19 @@ $wgAutopromote = array( /** * Automatically add a usergroup to any user who matches certain conditions. + * * Does not add the user to the group again if it has been removed. * Also, does not remove the group if the user no longer meets the criteria. * - * The format is + * The format is: + * @code * array( event => criteria, ... ) - * where event is - * 'onEdit' (when user edits) or 'onView' (when user views the wiki) - * and criteria has the same format as $wgAutopromote + * @endcode + * Where event is either: + * - 'onEdit' (when user edits) + * - 'onView' (when user views the wiki) + * + * Criteria has the same format as $wgAutopromote * * @see $wgAutopromote * @since 1.18 @@ -3811,16 +3978,23 @@ $wgAutopromoteOnceLogInRC = true; /** * $wgAddGroups and $wgRemoveGroups can be used to give finer control over who - * can assign which groups at Special:Userrights. Example configuration: + * can assign which groups at Special:Userrights. * + * @par Example: + * Bureaucrats can add any group: * @code - * // Bureaucrat can add any group * $wgAddGroups['bureaucrat'] = true; - * // Bureaucrats can only remove bots and sysops + * @endcode + * Bureaucrats can only remove bots and sysops: + * @code * $wgRemoveGroups['bureaucrat'] = array( 'bot', 'sysop' ); - * // Sysops can make bots + * @endcode + * Sysops can make bots: + * @code * $wgAddGroups['sysop'] = array( 'bot' ); - * // Sysops can disable other sysops in an emergency, and disable bots + * @endcode + * Sysops can disable other sysops in an emergency, and disable bots: + * @code * $wgRemoveGroups['sysop'] = array( 'sysop', 'bot' ); * @endcode */ @@ -3840,8 +4014,10 @@ $wgAvailableRights = array(); */ $wgDeleteRevisionsLimit = 0; -/** Number of accounts each IP address may create, 0 to disable. - * Requires memcached */ +/** + * Number of accounts each IP address may create, 0 to disable. + * + * @warning Requires memcached */ $wgAccountCreationThrottle = 0; /** @@ -3851,8 +4027,9 @@ $wgAccountCreationThrottle = 0; * There's no administrator override on-wiki, so be careful what you set. :) * May be an array of regexes or a single string for backwards compatibility. * - * See http://en.wikipedia.org/wiki/Regular_expression - * Note that each regex needs a beginning/end delimiter, eg: # or / + * @see http://en.wikipedia.org/wiki/Regular_expression + * + * @note Each regex needs a beginning/end delimiter, eg: # or / */ $wgSpamRegex = array(); @@ -3860,39 +4037,46 @@ $wgSpamRegex = array(); $wgSummarySpamRegex = array(); /** - * Whether to use DNS blacklists in $wgDnsBlacklistUrls to check for open proxies + * Whether to use DNS blacklists in $wgDnsBlacklistUrls to check for open + * proxies * @since 1.16 */ $wgEnableDnsBlacklist = false; /** - * @deprecated since 1.17 Use $wgEnableDnsBlacklist instead, only kept for backward - * compatibility + * @deprecated since 1.17 Use $wgEnableDnsBlacklist instead, only kept for + * backward compatibility. */ $wgEnableSorbs = false; /** - * List of DNS blacklists to use, if $wgEnableDnsBlacklist is true. This is an - * array of either a URL or an array with the URL and a key (should the blacklist - * require a key). For example: + * List of DNS blacklists to use, if $wgEnableDnsBlacklist is true. + * + * This is an array of either a URL or an array with the URL and a key (should + * the blacklist require a key). + * + * @par Example: * @code * $wgDnsBlacklistUrls = array( * // String containing URL - * 'http.dnsbl.sorbs.net', + * 'http.dnsbl.sorbs.net.', * // Array with URL and key, for services that require a key - * array( 'dnsbl.httpbl.net', 'mykey' ), + * array( 'dnsbl.httpbl.net.', 'mykey' ), * // Array with just the URL. While this works, it is recommended that you * // just use a string as shown above - * array( 'opm.tornevall.org' ) + * array( 'opm.tornevall.org.' ) * ); * @endcode + * + * @note You should end the domain name with a . to avoid searching your + * eventual domain search suffixes. * @since 1.16 */ $wgDnsBlacklistUrls = array( 'http.dnsbl.sorbs.net.' ); /** - * @deprecated since 1.17 Use $wgDnsBlacklistUrls instead, only kept for backward - * compatibility + * @deprecated since 1.17 Use $wgDnsBlacklistUrls instead, only kept for + * backward compatibility. */ $wgSorbsUrl = array(); @@ -3903,13 +4087,24 @@ $wgSorbsUrl = array(); $wgProxyWhitelist = array(); /** - * Simple rate limiter options to brake edit floods. Maximum number actions - * allowed in the given number of seconds; after that the violating client re- - * ceives HTTP 500 error pages until the period elapses. + * Simple rate limiter options to brake edit floods. * - * array( 4, 60 ) for a maximum of 4 hits in 60 seconds. + * Maximum number actions allowed in the given number of seconds; after that + * the violating client receives HTTP 500 error pages until the period + * elapses. + * + * @par Example: + * To set a generic maximum of 4 hits in 60 seconds: + * @code + * $wgRateLimits = array( 4, 60 ); + * @endcode * - * This option set is experimental and likely to change. Requires memcached. + * You could also limit per action and then type of users. See the inline + * code for a template to use. + * + * This option set is experimental and likely to change. + * + * @warning Requires memcached. */ $wgRateLimits = array( 'edit' => array( @@ -3958,7 +4153,8 @@ $wgQueryPageDefaultLimit = 50; /** * Limit password attempts to X attempts per Y seconds per IP per account. - * Requires memcached. + * + * @warning Requires memcached. */ $wgPasswordAttemptThrottle = array( 'count' => 5, 'seconds' => 300 ); @@ -3973,10 +4169,10 @@ $wgPasswordAttemptThrottle = array( 'count' => 5, 'seconds' => 300 ); * If you enable this, every editor's IP address will be scanned for open HTTP * proxies. * - * Don't enable this. Many sysops will report "hostile TCP port scans" to your - * ISP and ask for your server to be shut down. - * + * @warning Don't enable this. Many sysops will report "hostile TCP port scans" + * to your ISP and ask for your server to be shut down. * You have been warned. + * */ $wgBlockOpenProxies = false; /** Port we want to scan for a proxy */ @@ -4110,18 +4306,18 @@ $wgDebugRedirects = false; /** * If true, log debugging data from action=raw and load.php. - * This is normally false to avoid overlapping debug entries due to gen=css and - * gen=js requests. + * This is normally false to avoid overlapping debug entries due to gen=css + * and gen=js requests. */ $wgDebugRawPage = false; /** * Send debug data to an HTML comment in the output. * - * This may occasionally be useful when supporting a non-technical end-user. It's - * more secure than exposing the debug log file to the web, since the output only - * contains private data for the current user. But it's not ideal for development - * use since data is lost on fatal errors and redirects. + * This may occasionally be useful when supporting a non-technical end-user. + * It's more secure than exposing the debug log file to the web, since the + * output only contains private data for the current user. But it's not ideal + * for development use since data is lost on fatal errors and redirects. */ $wgDebugComments = false; @@ -4437,12 +4633,13 @@ $wgMWSuggestTemplate = false; $wgDisableSearchUpdate = false; /** - * List of namespaces which are searched by default. Example: + * List of namespaces which are searched by default. * - * <code> + * @par Example: + * @code * $wgNamespacesToBeSearchedDefault[NS_MAIN] = true; * $wgNamespacesToBeSearchedDefault[NS_PROJECT] = true; - * </code> + * @endcode */ $wgNamespacesToBeSearchedDefault = array( NS_MAIN => true, @@ -4450,9 +4647,9 @@ $wgNamespacesToBeSearchedDefault = array( /** * Namespaces to be searched when user clicks the "Help" tab - * on Special:Search + * on Special:Search. * - * Same format as $wgNamespacesToBeSearchedDefault + * Same format as $wgNamespacesToBeSearchedDefault. */ $wgNamespacesToBeSearchedHelp = array( NS_PROJECT => true, @@ -4460,8 +4657,10 @@ $wgNamespacesToBeSearchedHelp = array( ); /** - * If set to true the 'searcheverything' preference will be effective only for logged-in users. - * Useful for big wikis to maintain different search profiles for anonymous and logged-in users. + * If set to true the 'searcheverything' preference will be effective only for + * logged-in users. + * Useful for big wikis to maintain different search profiles for anonymous and + * logged-in users. * */ $wgSearchEverythingOnlyLoggedIn = false; @@ -4477,18 +4676,22 @@ $wgDisableInternalSearch = false; * If the URL includes '$1', this will be replaced with the URL-encoded * search term. * - * For example, to forward to Google you'd have something like: - * $wgSearchForwardUrl = 'http://www.google.com/search?q=$1' . - * '&domains=http://example.com' . - * '&sitesearch=http://example.com' . - * '&ie=utf-8&oe=utf-8'; + * @par Example: + * To forward to Google you'd have something like: + * @code + * $wgSearchForwardUrl = + * 'http://www.google.com/search?q=$1' . + * '&domains=http://example.com' . + * '&sitesearch=http://example.com' . + * '&ie=utf-8&oe=utf-8'; + * @endcode */ $wgSearchForwardUrl = null; /** - * Search form behavior - * true = use Go & Search buttons - * false = use Go button & Advanced search link + * Search form behavior. + * - true = use Go & Search buttons + * - false = use Go button & Advanced search link */ $wgUseTwoButtonsSearchForm = true; @@ -4505,11 +4708,13 @@ $wgSitemapNamespaces = false; * maintenance/generateSitemap.php script. * * This should be a map of namespace IDs to priority - * Example: + * @par Example: + * @code * $wgSitemapNamespacesPriorities = array( * NS_USER => '0.9', * NS_HELP => '0.0', * ); + * @endcode */ $wgSitemapNamespacesPriorities = false; @@ -4738,18 +4943,23 @@ $wgFeedDiffCutoff = 32768; /** Override the site's default RSS/ATOM feed for recentchanges that appears on * every page. Some sites might have a different feed they'd like to promote * instead of the RC feed (maybe like a "Recent New Articles" or "Breaking news" one). - * Ex: $wgSiteFeed['format'] = "http://example.com/somefeed.xml"; Format can be one - * of either 'rss' or 'atom'. + * Should be a format as key (either 'rss' or 'atom') and an URL to the feed + * as value. + * @par Example: + * Configure the 'atom' feed to http://example.com/somefeed.xml + * @code + * $wgSiteFeed['atom'] = "http://example.com/somefeed.xml"; + * @endcode */ $wgOverrideSiteFeed = array(); /** - * Available feeds objects + * Available feeds objects. * Should probably only be defined when a page is syndicated ie when - * $wgOut->isSyndicated() is true + * $wgOut->isSyndicated() is true. */ $wgFeedClasses = array( - 'rss' => 'RSSFeed', + 'rss' => 'RSSFeed', 'atom' => 'AtomFeed', ); @@ -4908,9 +5118,9 @@ $wgExportAllowListContributors = false; * can become *insanely large* and could easily break your wiki, * it's disabled by default for now. * - * There's a HARD CODED limit of 5 levels of recursion to prevent a - * crazy-big export from being done by someone setting the depth - * number too high. In other words, last resort safety net. + * @warning There's a HARD CODED limit of 5 levels of recursion to prevent a + * crazy-big export from being done by someone setting the depth number too + * high. In other words, last resort safety net. */ $wgExportMaxLinkDepth = 0; @@ -4932,7 +5142,8 @@ $wgExportAllowAll = false; */ /** - * A list of callback functions which are called once MediaWiki is fully initialised + * A list of callback functions which are called once MediaWiki is fully + * initialised */ $wgExtensionFunctions = array(); @@ -4947,9 +5158,10 @@ $wgExtensionFunctions = array(); * Variables defined in extensions will override conflicting variables defined * in the core. * - * Example: + * @par Example: + * @code * $wgExtensionMessagesFiles['ConfirmEdit'] = dirname(__FILE__).'/ConfirmEdit.i18n.php'; - * + * @endcode */ $wgExtensionMessagesFiles = array(); @@ -4963,7 +5175,9 @@ $wgExtensionMessagesFiles = array(); * Registration is done with $pout->addOutputHook( $tag, $data ). * * The callback has the form: + * @code * function outputHook( $outputPage, $parserOutput, $data ) { ... } + * @endcode */ $wgParserOutputHooks = array(); @@ -4994,7 +5208,7 @@ $wgAutoloadClasses = array(); * urls, descriptions and pointers to localized description msgs. Note that * the version, url, description and descriptionmsg key can be omitted. * - * <code> + * @code * $wgExtensionCredits[$type][] = array( * 'name' => 'Example extension', * 'version' => 1.9, @@ -5004,7 +5218,7 @@ $wgAutoloadClasses = array(); * 'description' => 'An example extension', * 'descriptionmsg' => 'exampleextension-desc', * ); - * </code> + * @endcode * * Where $type is 'specialpage', 'parserhook', 'variable', 'media' or 'other'. * Where 'descriptionmsg' can be an array with message key and parameters: @@ -5020,12 +5234,30 @@ $wgAuth = null; /** * Global list of hooks. - * Add a hook by doing: + * + * The key is one of the events made available by MediaWiki, you can find + * a description for most of them in docs/hooks.txt. The array is used + * internally by Hook:run(). + * + * The value can be one of: + * + * - A function name: + * @code * $wgHooks['event_name'][] = $function; - * or: + * @endcode + * - A function with some data: + * @code * $wgHooks['event_name'][] = array($function, $data); - * or: + * @endcode + * - A an object method: + * @code * $wgHooks['event_name'][] = array($object, 'method'); + * @endcode + * + * @warning You should always append to an event array or you will end up + * deleting a previous registered hook. + * + * @todo Does it support PHP closures? */ $wgHooks = array(); @@ -5179,11 +5411,13 @@ $wgLogRestrictions = array( * * See $wgLogTypes for a list of available log types. * - * For example: + * @par Example: + * @code * $wgFilterLogTypes => array( * 'move' => true, * 'import' => false, * ); + * @endcode * * Will display show/hide links for the move and import logs. Move logs will be * hidden by default unless the link is clicked. Import logs will be shown by @@ -5202,7 +5436,7 @@ $wgFilterLogTypes = array( * * Extensions with custom log types may add to this array. * - * Since 1.19, if you follow the naming convention log-name-TYPE, + * @since 1.19, if you follow the naming convention log-name-TYPE, * where TYPE is your log type, yoy don't need to use this array. */ $wgLogNames = array( @@ -5225,7 +5459,7 @@ $wgLogNames = array( * * Extensions with custom log types may add to this array. * - * Since 1.19, if you follow the naming convention log-description-TYPE, + * @since 1.19, if you follow the naming convention log-description-TYPE, * where TYPE is your log type, yoy don't need to use this array. */ $wgLogHeaders = array( @@ -5504,8 +5738,10 @@ $wgDefaultRobotPolicy = 'index,follow'; * URLs, so search engine spiders risk getting lost in a maze of twisty special * pages, all alike, and never reaching your actual content. * - * Example: + * @par Example: + * @code * $wgNamespaceRobotPolicies = array( NS_TALK => 'noindex' ); + * @endcode */ $wgNamespaceRobotPolicies = array(); @@ -5513,10 +5749,18 @@ $wgNamespaceRobotPolicies = array(); * Robot policies per article. These override the per-namespace robot policies. * Must be in the form of an array where the key part is a properly canonical- * ised text form title and the value is a robot policy. - * Example: - * $wgArticleRobotPolicies = array( 'Main Page' => 'noindex,follow', - * 'User:Bob' => 'index,follow' ); - * Example that DOES NOT WORK because the names are not canonical text forms: + * + * @par Example: + * @code + * $wgArticleRobotPolicies = array( + * 'Main Page' => 'noindex,follow', + * 'User:Bob' => 'index,follow', + * ); + * @endcode + * + * @par Example that DOES NOT WORK because the names are not canonical text + * forms: + * @code * $wgArticleRobotPolicies = array( * # Underscore, not space! * 'Main_Page' => 'noindex,follow', @@ -5525,6 +5769,7 @@ $wgNamespaceRobotPolicies = array(); * # Needs to be "Abc", not "abc" (unless $wgCapitalLinks is false for that namespace)! * 'abc' => 'noindex,nofollow' * ); + * @endcode */ $wgArticleRobotPolicies = array(); @@ -5532,8 +5777,11 @@ $wgArticleRobotPolicies = array(); * An array of namespace keys in which the __INDEX__/__NOINDEX__ magic words * will not function, so users can't decide whether pages in that namespace are * indexed by search engines. If set to null, default to $wgContentNamespaces. - * Example: + * + * @par Example: + * @code * $wgExemptFromUserRobotsControl = array( NS_MAIN, NS_TALK, NS_PROJECT ); + * @endcode */ $wgExemptFromUserRobotsControl = null; @@ -5563,9 +5811,10 @@ $wgEnableAPI = true; $wgEnableWriteAPI = true; /** - * API module extensions + * API module extensions. * Associative array mapping module name to class name. * Extension modules may override the core modules. + * @todo Describe each of the variables, group them and add examples */ $wgAPIModules = array(); $wgAPIMetaModules = array(); @@ -5580,7 +5829,7 @@ $wgAPIMaxDBRows = 5000; /** * The maximum size (in bytes) of an API result. - * Don't set this lower than $wgMaxArticleSize*1024 + * @warning Do not set this lower than $wgMaxArticleSize*1024 */ $wgAPIMaxResultSize = 8388608; @@ -5635,17 +5884,18 @@ $wgAjaxLicensePreview = true; * This is currently only used by the API (requests to api.php) * $wgCrossSiteAJAXdomains can be set using a wildcard syntax: * - * '*' matches any number of characters - * '?' matches any 1 character - * - * Example: - $wgCrossSiteAJAXdomains = array( - 'www.mediawiki.org', - '*.wikipedia.org', - '*.wikimedia.org', - '*.wiktionary.org', - ); + * - '*' matches any number of characters + * - '?' matches any 1 character * + * @par Example: + * @code + * $wgCrossSiteAJAXdomains = array( + * 'www.mediawiki.org', + * '*.wikipedia.org', + * '*.wikimedia.org', + * '*.wiktionary.org', + * ); + * @endcode */ $wgCrossSiteAJAXdomains = array(); @@ -5749,7 +5999,7 @@ $wgUpdateRowsPerQuery = 100; /** * The build directory for HipHop compilation. - * Defaults to $IP/maintenance/hiphop/build. + * Defaults to '$IP/maintenance/hiphop/build'. */ $wgHipHopBuildDirectory = false; @@ -5769,8 +6019,9 @@ $wgHipHopCompilerProcs = 'detect'; * * To compile extensions with HipHop, set $wgExtensionsDirectory correctly, * and use code like: - * + * @code * require( MWInit::extensionSetupPath( 'Extension/Extension.php' ) ); + * @endcode * * to include the extension setup file from LocalSettings.php. It is not * necessary to set this variable unless you use MWInit::extensionSetupPath(). @@ -5815,9 +6066,11 @@ $wgExternalDiffEngine = false; /** * Disable redirects to special pages and interwiki redirects, which use a 302 - * and have no "redirected from" link. Note this is only for articles with #Redirect - * in them. URL's containing a local interwiki prefix (or a non-canonical special - * page name) are still hard redirected regardless of this setting. + * and have no "redirected from" link. + * + * @note This is only for articles with #REDIRECT in them. URL's containing a + * local interwiki prefix (or a non-canonical special page name) are still hard + * redirected regardless of this setting. */ $wgDisableHardRedirects = false; @@ -5828,8 +6081,8 @@ $wgDisableHardRedirects = false; $wgLinkHolderBatchSize = 1000; /** - * By default MediaWiki does not register links pointing to same server in externallinks dataset, - * use this value to override: + * By default MediaWiki does not register links pointing to same server in + * externallinks dataset, use this value to override: */ $wgRegisterInternalExternals = false; @@ -5857,8 +6110,10 @@ $wgRedirectOnLogin = null; * This configuration array maps pool types to an associative array. The only * defined key in the associative array is "class", which gives the class name. * The remaining elements are passed through to the class as constructor - * parameters. Example: + * parameters. * + * @par Example: + * @code * $wgPoolCounterConf = array( 'ArticleView' => array( * 'class' => 'PoolCounter_Client', * 'timeout' => 15, // wait timeout in seconds @@ -5866,6 +6121,7 @@ $wgRedirectOnLogin = null; * 'maxqueue' => 50, // maximum number of total threads in each pool * ... any extension-specific options... * ); + * @endcode */ $wgPoolCounterConf = null; -- 2.20.1