Complete documentation of source code.

Doxyfile

@@ -778,7 +778,7 @@ RECURSIVE              = NO
 # Note that relative paths are relative to the directory from which doxygen is
 # run.
 
-EXCLUDE                =
+EXCLUDE                = README.md
 
 # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
 # directories that are symbolic links (a Unix file system feature) are excluded
@@ -892,7 +892,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1335,7 +1335,7 @@ ECLIPSE_DOC_ID         = org.doxygen.Project
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-DISABLE_INDEX          = NO
+DISABLE_INDEX          = YES
 
 # The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
 # structure should be generated to display hierarchical information. If the tag
@@ -1973,7 +1973,11 @@ SKIP_FUNCTION_MACROS   = YES
 # the path). If a tag file is not located in the directory in which doxygen is
 # run, you must also specify the path to the tagfile here.
 
-TAGFILES               = "Doxygen_mwtags.xml = https://doc.wikimedia.org/mediawiki-core/REL1_23/php/html"
+# Documentation was cluttered when all MediaWiki content was included. It's
+# too bad for the missing links to the two parent classes (Maintenance and
+# SpecialPage), but if users want to look up these, they can just head over
+# to mediawiki.org.
+# TAGFILES               = "Doxygen_mwtags.xml = https://doc.wikimedia.org/mediawiki-core/REL1_23/php/html"
 
 # When a file name is specified after GENERATE_TAGFILE, doxygen will create a
 # tag file that is based on the input files it reads. See section "Linking to

LinkTitles.body.php

@@ -1,7 +1,5 @@
 <?php
 /*
- *      \file LinkTitles.body.php
- *      
  *      Copyright 2012-2014 Daniel Kraus <krada@gmx.net> ('bovender')
  *      
  *      This program is free software; you can redistribute it and/or modify
@@ -19,14 +17,18 @@
  *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  *      MA 02110-1301, USA.
  */
+	/// @file
  
+	/// Helper function for development and debugging.
+  /// @param $var Any variable. Raw content will be dumped to stderr.
+	/// @return undefined
 	function dump($var) {
 			error_log(print_r($var, TRUE) . "\n", 3, 'php://stderr');
 	};
 
-	/// Main function of the extensions. Sets up parser hooks and performs the 
+	/// Central class of the extension. Sets up parser hooks.
-	/// actual parsing.
+	/// This class contains only static functions; do not instantiate.
-	/// TODO: Use the current PageContentSave hook rather than the deprecated ArticleSave hook.
+	/// @todo Use the current PageContentSave hook rather than the deprecated ArticleSave hook.
 	class LinkTitles {
 		/// Setup function, hooks the extension's functions to MediaWiki events.
 		public static function setup() {
@@ -42,9 +44,7 @@
 			$wgHooks['ParserBeforeTidy'][] = 'LinkTitles::removeMagicWord';
 		}
 
-		/// This function is hooked to the ArticleSave event.
+		/// Event handler that is hooked to the ArticleSave event.
-		/// It will be called whenever a page is about to be 
-		/// saved.
 		public static function onArticleSave( &$article, &$user, &$text, &$summary,
 				$minor, $watchthis, $sectionanchor, &$flags, &$status ) {
 
@@ -54,8 +54,9 @@
 			return $minor or self::parseContent( $article, $text );
 		}
 
-		/// Called when an ArticleAfterFetchContent event occurs; this requires the
+		/// Event handler that is hooked to the ArticleAfterFetchContent event.
-		/// $wgLinkTitlesParseOnRender option to be set to 'true'
+		/// @param $article Article object
+		/// @param $content String that holds the article content
 		public static function onArticleAfterFetchContent( &$article, &$content ) {
 			// The ArticleAfterFetchContent event is triggered whenever page content
 			// is retrieved from the database, i.e. also for editing etc.
@@ -68,7 +69,10 @@
 			return true;
 		}
 
-		/// This function performs the actual parsing of the content.
+		/// Core function of the extension, performs the actual parsing of the content.
+		/// @param $article Article object
+		/// @param $text    String that holds the article content
+		/// @returns true
 		static function parseContent( &$article, &$text ) {
 
 			// If the page contains the magic word '__NOAUTOLINKS__', do not parse
@@ -138,8 +142,8 @@
 				'("' . implode( '", "',$wgLinkTitlesBlackList ) . '")' );
 
 
-			// Build an SQL query and fetch all page titles ordered
+			// Build an SQL query and fetch all page titles ordered by length from 
-			// by length from shortest to longest.
+			// shortest to longest.
 			// Only titles from 'normal' pages (namespace uid = 0)
 			// are returned.
 			// Since the db may be sqlite, we need a try..catch structure
@@ -298,6 +302,11 @@
 		/// Automatically processes a single page, given a $title Title object.
 		/// This function is called by the SpecialLinkTitles class and the 
 		/// LinkTitlesJob class.
+		/// @param $title    `Title` object that identifies the page.
+		/// @param $context  Object that implements IContextProvider.
+		///                  If in doubt, call MediaWiki's `RequestContext::getMain()`
+		///                  to obtain such an object.
+		/// @returns undefined
 		public static function processPage($title, $context) {
 			// TODO: make this namespace-aware
 			$titleObj = Title::makeTitle(0, $title);
@@ -315,6 +324,9 @@
 
 		/// Remove the magic words that this extension introduces from the 
 		/// $text, so that they do not appear on the rendered page.
+		/// @param $parser Parser object
+		/// @param $text   String that contains the page content.
+		/// @returns true
 		static function removeMagicWord( &$parser, &$text ) {
 			$mwa = new MagicWordArray(array(
 				'MAG_LINKTITLES_NOAUTOLINKS',
@@ -326,4 +338,4 @@
 		}
 	}
 
-	// vim: ts=2:sw=2:noet
+// vim: ts=2:sw=2:noet:comments^=\:///

LinkTitles.cli.php

@@ -1,7 +1,5 @@
 <?php
 /*
- *      \file LinkTitles.cli.php
- *      
  *      Copyright 2012-2014 Daniel Kraus <krada@gmx.net> ('bovender')
  *      
  *      This program is free software; you can redistribute it and/or modify
@@ -47,7 +45,15 @@ else
 
 require_once( dirname( __FILE__ ) . "/LinkTitles.body.php" );
  
+/// Core class of the maintanance script.
+/// @note Note that the execution of maintenance scripts is prohibited for 
+/// an Apache web server due to a `.htaccess` file that declares `deny from 
+/// all`. Other webservers may exhibit different behavior. Be aware that 
+/// anybody who is able to execute this script may place a high load on the 
+/// server.
+/// @ingroup batch
 class LinkTitlesCli extends Maintenance {
+	/// The constructor adds a description and one option.
 	public function __construct() {
 		parent::__construct();
 		$this->addDescription("Iterates over wiki pages and automatically adds links to other pages.");
@@ -60,6 +66,10 @@ class LinkTitlesCli extends Maintenance {
 		);
 	}
 
+	/// Main function of the maintenance script.
+	/// Will iterate over all pages in the wiki (starting at a certain index, 
+	/// if the `--start` option is given) and call LinkTitles::processPage() for 
+	/// each page.
 	public function execute() {
 		$index = intval($this->getOption('start', 0));
 		if ( $index < 0 ) {
@@ -107,5 +117,4 @@ if( defined('RUN_MAINTENANCE_IF_MAIN') ) {
 	require_once( DO_MAINTENANCE ); # Make this work on versions before 1.17
 }
 
-// vim: ts=2:sw=2:noet
+// vim: ts=2:sw=2:noet:comments^=\:///
-

LinkTitles.i18n.magic.php

@@ -1,9 +1,11 @@
 <?php
-/*! \file LinkTitles.i18n.magic.php
+/*! @file LinkTitles.i18n.magic.php
  */
  
+/// Holds the two magic words that the extension provides.
 $magicWords = array();
 
+/// Default magic words in English.
 $magicWords['en'] = array(
 	'MAG_LINKTITLES_NOAUTOLINKS' => array(0, '__NOAUTOLINKS__'),
 	'MAG_LINKTITLES_NOTARGET' => array(0, '__NOAUTOLINKTARGET__')

LinkTitles.i18n.php

@@ -1,14 +1,17 @@
 <?php
-/*! \file LinkTitles.i18n.php
+/** @file LinkTitles.i18n.php
  */
  
+/// Holds messages that the extension provides.
 $messages = array();
 
+/// English messages.
 $messages['en'] = array(
 	'linktitles' => 'LinkTitles',
 	'linktitles-desc' => 'Automatically adds links to existing pages whenever a page is saved.',
 );
 
+/// German messages.
 $messages['de'] = array(
 	'linktitles-desc' => 'Fügt beim Speichern von Seiten automatisch Querverweise zu vorhandenen Seiten ein.',
 );

LinkTitles.php

@@ -1,7 +1,5 @@
 <?php
 /*
- *      \file LinkTitles.php
- *      
  *      Copyright 2012-2014 Daniel Kraus <krada@gmx.net> ('bovender')
  *      
  *      This program is free software; you can redistribute it and/or modify
@@ -19,9 +17,18 @@
  *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  *      MA 02110-1301, USA.
  */
+
+	/// @file
+	/// This file will be loaded by MediaWiki if the extension is included in 
+	/// `LocalSettings.php`. It sets up the classes for auto-loading, 
+	/// announces metadata, and defines a number of @link config configuration 
+	/// variables @endlink.
+
+	/// @cond
   if ( !defined( 'MEDIAWIKI' ) ) {
     die( 'Not an entry point.' );
   }
+	/// @endcond
 
 	/*
 		error_reporting(E_ALL);
@@ -31,20 +38,118 @@
 		$wgCacheDirectory = false;
 	*/
 
-	// Configuration variables
+	/// @defgroup config Configuration
+  /// The global configuration variables can be overriden in the local 
+	/// `LocalSettings.php` file just like with any other extension.
+	/// These variables are all defined in LinkTitles.php.
+
+	/// Controls precedence of page titles. If true, pages with shorter titles 
+	/// are given preference over pages with longer titles (e.g., link to 
+	/// 'Media' rather than 'MediaWiki'). If false (default), longer titles 
+	/// (which tend to be more specific) are given precedence (e.g., link to 
+	/// 'MediaWiki' rather than 'Media' if both pages exist).
+	/// @ingroup config
 	$wgLinkTitlesPreferShortTitles = false;	
+
+	/// The minimum number of characters in a title that is required for it to 
+	/// be automatically linked to.
+	/// @ingroup config
 	$wgLinkTitlesMinimumTitleLength = 3;
+
+	/// Determines whether or not to insert links into headings.
+	/// @ingroup config
 	$wgLinkTitlesParseHeadings = false;
+
+	/// Important configuration variable that determines when the extension 
+	/// will process a page. If set to true in `LocalSettings.php`, links will 
+	/// be inserted whenever a page is edited and saved (unless 'minor 
+	/// modifications' is checked). If set to false, the extension will not do 
+	/// anything when a page is edited 
+	/// and saved.
+	/// @ingroup config
 	$wgLinkTitlesParseOnEdit = true;
+
+	/// Less important configuration variable that determines when the 
+	/// extension will process a page. If set to true in LocalSettings.php, 
+	/// links will be inserted when a page is rendered for viewing.
+	/// @note Whether a page will be rendered or just fetched from the page 
+	/// cache is unpredictable. Therefore, pages may not always be parsed for 
+	/// possible links when this variable is set to true.
+	/// @warning Setting this to true has the potential to affect lots of page 
+	/// views (but see note regarding cached pages).
+	/// @ingroup config
 	$wgLinkTitlesParseOnRender = false;
+
+	/// Determines whether to parse text inside templates. If this is set to 
+	/// true in LocalSettings.php, 
+	/// @ingroup config
 	$wgLinkTitlesSkipTemplates = false;
+
+	/// Blacklist of page titles that should never be linked. 
+	/// @ingroup config
 	$wgLinkTitlesBlackList = array();
+
+	/// Determines whether to link only the first occurrence of a page 
+	/// title on a page or all occurrences. Default is false: All occurrences 
+	/// on a page are linked.
+	/// @ingroup config
+
 	$wgLinkTitlesFirstOnly = false;
+
+	/// Determines whether a page title must occur at the start of a word in 
+	/// order for it to be linked. Example: Given a page 'Media' and an 
+	/// article that contains the word 'Multimedia', the default setting 
+	/// (`true`) will prevent the page from being linked. If this setting is 
+	/// overriden in `LocalSettings.php` to be `false`, a link would be 
+	/// inserted: `Multi[[media]]`.
+	/// @note If both $wgLinkTitlesWordStartOnly and $wgLinkTitlesWordEndOnly 
+	/// are overriden to `false` in `LocalSettings.php`, you may get weird 
+	/// linking. As a (contrieved) example, consider a wiki that has a page 
+	/// "spa", then the word "namespace" in a technical article would be 
+	/// linked as `name[[spa]]ce`, which is likely not what you want.
+	/// @ingroup config
 	$wgLinkTitlesWordStartOnly = true;
+
+	/// Determines whether a page title must end with the end of a word in 
+	/// order for it to be linked. Example: Given a page 'Media' and an 
+	/// article that contains the word 'MediaWiki', the default setting 
+	/// (`true`) will prevent the page from being linked, because both words 
+	/// have different endings. If this setting is overriden in 
+	/// `LocalSettings.php` to be `false`, a link would be inserted: 
+	/// `[[Media]]wiki`.
+	/// @note Setting this to false may have undesired effects because there 
+	/// are many short words that may randomly occur in longer words, but are 
+	/// semantically unrelated.
+	/// @note If both $wgLinkTitlesWordStartOnly and $wgLinkTitlesWordEndOnly 
+	/// are overriden to `false` in `LocalSettings.php`, you may get weird 
+	/// linking. As a (contrieved) example, consider a wiki that has a page 
+	/// "spa", then the word "namespace" in a technical article would be 
+	/// linked as `name[[spa]]ce`, which is likely not what you want.
+	/// @ingroup config
 	$wgLinkTitlesWordEndOnly = true;
+
+	/// Important setting that controls the extension's smart mode of 
+	/// operation. With smart mode turned on (default), the extension will 
+	/// first link all occurrences of a page title on a page in a 
+	/// case-sensitive manner (but see note). It will then perform a second 
+	/// pass in a case-__in__sensitive manner. For example, if you have a page 
+	/// called "IgAN" (abbreviation for IgA nephritis, a kidney disease) and 
+	/// someone writes the alternative form "Igan" in their article, then the 
+	/// page would not be linked if smart mode is turned off.
+	/// @note Because smart mode constitutes two-pass processing of a page, 
+	/// rather than single-pass, the processing time will increase. This may 
+	/// not be noticeable on single page saves, but may play a role during 
+	/// @link batch batch processing @endlink.
+	/// @ingroup config
 	$wgLinkTitlesSmartMode = true;
+
+	/// Time limit for online batch processing. This determines the maximum 
+	/// amount of time in seconds that page processing will take before a 
+	/// refresh of the special page is issued.
+	/// @ingroup config
 	$wgLinkTitlesTimeLimit = 0.2;
 
+	/// @cond
   $wgExtensionCredits['parserhook'][] = array(
     'path'           => __FILE__,
     'name'           => 'LinkTitles',
@@ -63,8 +168,19 @@
 	// Settings for the batch-processing special page
 	$wgSpecialPages['LinkTitles'] = 'SpecialLinkTitles';
 	$wgSpecialPageGroups['LinkTitles'] = 'other';
-	$wgGroupPermissions['sysop']['linktitles-batch'] = true;
+	/// @endcond
+	
+	/// The @link SpecialLinkTitles special page @endlink provides a distinct 
+	/// right `linktitles-batch`. A user must be granted this right in order 
+	/// to be able to visit this page.
 	$wgAvailableRights[] = 'linktitles-batch';
 
-	// vim: ts=2:sw=2:noet
+	/// Grants the `linktitles-batch` right to sysops by default.
+	/// Override this only with care. If anybody can execute the
+	/// @link SpecialLinkTitles special page @endlink the server might 
+	/// experience high loads.
+	/// @ingroup config
+	$wgGroupPermissions['sysop']['linktitles-batch'] = true;
+
+// vim: ts=2:sw=2:noet:comments^=\:///
 

README.md

@@ -4,3 +4,7 @@ LinkTitles
 MediaWiki extension that automatically adds links to words that match titles of existing pages.
 
 For more information, see http://www.mediawiki.org/wiki/Extension:LinkTitles
+
+Source code documentation can be found at the [Github project
+pages](http://bovender.github.io/LinkTitles).
+

README_DOC.md

@@ -0,0 +1,60 @@
+@mainpage LinkTitles
+@author    [Daniel Kraus (bovender)](http://www.mediawiki.org/wiki/User:Bovender)
+@date      2012-2014
+@copyright [GNU GPL v2](http://www.gnu.org/licenses/gpl-2.0.html)
+
+%LinkTitles source code documentation
+=====================================
+
+This is the [source code][] documentation for the [LinkTitles][] extension
+for [MediaWiki][].
+
+The central class is LinkTitles, which contains only static functions. If
+you are looking for the linking algorithm, inspect the
+LinkTitles::parseContent() function.
+
+The extension provides two methods for batch-processing of pages. One is a
+@link SpecialLinkTitles special page @endlink that provides web-access (by
+default restricted to sysops). The other is a @link LinkTitlesCli
+maintenance script @endlink that can be called from the command line if you
+have access to your server and are authorized to run php from the command
+line.
+
+@ref config variables are defined in LinkTitles.php.
+
+@note The source code that is referenced in this documentation may not
+necessarily reflect the latest code in the repository! Make sure to check
+out the Git repository for the latest code.
+
+
+A note on the publication of the source code documentation
+----------------------------------------------------------
+
+The documentation is automatically generated from the source code by
+[Doxygen][]. A special branch of the Git repository, [`gh-pages`][gh-pages],
+was created that holds the [GitHub project pages][github-pages]. To make use
+of the project page facility provided by GitHub, the root directory of a
+repository needs to be [erased][gh-erase] first before content is added.
+Since this would remove the source code from which the documentation is
+generated, deleting all files in the root directory while on the `gh-pages`
+branch was not feasible.
+
+The solution was to pull down the `gh-pages` branch as a submodule into an
+empty `gh-pages\` subdirectory:
+
+~~~~{.sh}
+git submodule add -b gh-pages git@github.com:bovender/LinkTitles.git gh-pages
+~~~~
+
+This command tells git-submodule to only pull down the `gh-pages` branch as
+a submodule -- we don't need to pull down the master branch into the same
+repository again.
+
+
+[source code]:  http://github.com/bovender/LinkTitles
+[LinkTitles]:   http://www.mediawiki.org/wiki/Extension:LinkTitles
+[MediaWiki]:    http://www.mediawiki.org
+[Doxygen]:      http://www.doxygen.org
+[github-pages]: https://pages.github.com/
+[gh-pages]:     https://github.com/bovender/LinkTitles/tree/gh-pages
+[gh-erase]:     https://help.github.com/articles/creating-project-pages-manually#create-a-gh-pages-branch

SpecialLinkTitles.php

@@ -1,7 +1,5 @@
 <?php
 /*
- *      \file SpecialLinkTitles.php
- *
  *      Copyright 2012-2014 Daniel Kraus <krada@gmx.net> ('bovender')
  *
  *      This program is free software; you can redistribute it and/or modify
@@ -19,15 +17,21 @@
  *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  *      MA 02110-1301, USA.
  */
+/// @defgroup batch Batch processing
 
+	/// @cond
   if ( !defined( 'MEDIAWIKI' ) ) {
     die( 'Not an entry point.' );
 	}
+	/// @endcond
  
 /// Provides a special page that can be used to batch-process all pages in 
 /// the wiki. By default, this can only be performed by sysops.
+/// @ingroup batch
 class SpecialLinkTitles extends SpecialPage {
 
+	/// Constructor. Announces the special page title and required user right 
+	/// to the parent constructor.
 	function __construct() {
 		// the second parameter in the following function call ensures that only 
 		// users who have the 'linktitles-batch' right get to see this page (by 
@@ -37,6 +41,7 @@ class SpecialLinkTitles extends SpecialPage {
 
 	/// Entry function of the special page class. Will abort if the user does 
 	/// not have appropriate permissions ('linktitles-batch').
+	/// @returns undefined
 	function execute($par) {
 		// Prevent non-authorized users from executing the batch processing.
 		if (  !$this->userCanExecute( $this->getUser() )  ) {
@@ -64,13 +69,15 @@ class SpecialLinkTitles extends SpecialPage {
 		{
 			$this->buildInfoPage($request, $output);
 		}
-
 	}
 
 
 	/// Processes wiki articles, starting at the page indicated by 
 	/// $startTitle. If $wgLinkTitlesTimeLimit is reached before all pages are 
 	/// processed, returns the title of the next page that needs processing.
+	/// @param $request WebRequest object that is associated with the special 
+	///                 page.
+	/// @param $output  Output object that the special page is equipped with.
 	private function process(&$request, &$output) {
 		global $wgLinkTitlesTimeLimit;
 
@@ -147,7 +154,6 @@ class SpecialLinkTitles extends SpecialPage {
 		}
 	}
 
-
 	/// Adds WikiText to the output containing information about the extension 
 	/// and a form and button to start linking.
 	private function buildInfoPage(&$request, &$output) {
@@ -179,8 +185,13 @@ EOF
 	}
 
 	/// Produces informative output in WikiText format to show while working.
-	private function addProgressInfo(&$output, $curTitle, $start, $end) {
+	/// @param $output    Output object.
-		$progress = $start / $end * 100;
+	/// @param $curTitle  Title of the currently processed page.
+	/// @param $index     Index of the currently processed page.     
+	/// @param $end       Last index that will be processed (i.e., number of 
+	///                   pages).
+	private function addProgressInfo(&$output, $curTitle, $index, $end) {
+		$progress = $index / $end * 100;
 		$percent = sprintf("%01.1f", $progress);
 
 		$output->addWikiText(
@@ -195,7 +206,7 @@ EOF
 		);
 		$output->addHTML(
 <<<EOF
-<p>Page ${start} of ${end}.</p>
+<p>Page ${index} of ${end}.</p>
 <div style="width:100%; padding:2px; border:1px solid #000; position: relative;
 		margin-bottom:16px;">
 	<span style="position: absolute; left: 50%; font-weight:bold; color:#555;">
@@ -215,6 +226,12 @@ EOF
 
 	/// Generates an HTML form and JavaScript to automatically submit the 
 	/// form.
+	/// @param $url     URL to reload with a POST request.
+	/// @param $start   Index of the next page that shall be processed.
+	/// @param $end     Index of the last page to be processed.
+	/// @param $reloads Counter that holds the number of reloads so far.
+	/// @returns        String that holds the HTML for a form and a
+	///                 JavaScript command.
 	private function getReloaderForm($url, $start, $end, $reloads) {
 		return
 <<<EOF
@@ -231,6 +248,11 @@ EOF
 	}
 
 	/// Adds statistics to the page when all processing is done.
+	/// @param $output  Output object
+	/// @param $start   Index of the first page that was processed.
+	/// @param $end     Index of the last processed page.
+	/// @param $reloads Number of reloads of the page.
+	/// @returns undefined
 	private function addCompletedInfo(&$output, $start, $end, $reloads) {
 		global $wgLinkTitlesTimeLimit;
 		$pagesPerReload = sprintf('%0.1f', $end / $reloads);
@@ -252,7 +274,9 @@ EOF
 	}
 
 	/// Counts the number of pages in a read-access wiki database ($dbr).
-	private function countPages($dbr) {
+	/// @param $dbr Read-only `Database` object.
+	/// @returns Number of pages in the default namespace (0) of the wiki.
+	private function countPages(&$dbr) {
 		$res = $dbr->select(
 			'page',
 			'page_id', 
@@ -264,4 +288,5 @@ EOF
 		return $res->numRows();
 	}
 }
-// vim: ts=2:sw=2:noet
+
+// vim: ts=2:sw=2:noet:comments^=\:///