! Rename SetReserve() to SetReserved() (ManageRegistration, handler for subaction reservednames)

! You guessed: code documentation for a few more files.

Sources/ManageRegistration.php

@@ -1,6 +1,9 @@
 <?php
 
 /**
+ * This file helps the administrator setting registration settings and policy
+ * as well as allow the administrator to register new members themselves.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,45 +17,15 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file helps the administrator setting registration settings and policy
-	as well as allow the administrator to register new members themselves.
-
-	void RegCenter()
-		- entrance point for the registration center.
-		- accessed by ?action=admin;area=regcenter.
-		- requires either the moderate_forum or the admin_forum permission.
-		- loads the Login language file and the Register template.
-		- calls the right function based on the subaction.
-
-	void AdminRegister()
-		- a function to register a new member from the admin center.
-		- accessed by ?action=admin;area=regcenter;sa=register
-		- requires the moderate_forum permission.
-		- uses the admin_register sub template of the Register template.
-		- allows assigning a primary group to the member being registered.
-
-	void EditAgreement()
-		- allows the administrator to edit the registration agreement, and
-		  choose whether it should be shown or not.
-		- accessed by ?action=admin;area=regcenter;sa=agreement.
-		- uses the Admin template and the edit_agreement sub template.
-		- requires the admin_forum permission.
-		- uses the edit_agreement administration area.
-		- writes and saves the agreement to the agreement.txt file.
-
-	void SetReserve()
-		- set the names under which users are not allowed to register.
-		- accessed by ?action=admin;area=regcenter;sa=reservednames.
-		- requires the admin_forum permission.
-		- uses the reserved_words sub template of the Register template.
-
-	void ModifyRegistrationSettings()
-		- set general registration settings and Coppa compliance settings.
-		- accessed by ?action=admin;area=regcenter;sa=settings.
-		- requires the admin_forum permission.
-*/
-
-// Main handling function for the admin approval center
+/**
+ * Entrance point for the registration center, it checks permisions and forwards
+ * to the right function based on the subaction.
+ * Accessed by ?action=admin;area=regcenter.
+ * Requires either the moderate_forum or the admin_forum permission.
+ *
+ * @uses Login language file
+ * @uses Register template.
+ */
 function RegCenter()
 {
 	global $modSettings, $context, $txt, $scripturl;
@@ -64,7 +37,7 @@ function RegCenter()
 	$subActions = array(
 		'register' => array('AdminRegister', 'moderate_forum'),
 		'agreement' => array('EditAgreement', 'admin_forum'),
-		'reservednames' => array('SetReserve', 'admin_forum'),
+		'reservednames' => array('SetReserved', 'admin_forum'),
 		'settings' => array('ModifyRegistrationSettings', 'admin_forum'),
 	);
 
@@ -103,7 +76,14 @@ function RegCenter()
 	$subActions[$context['sub_action']][0]();
 }
 
-// This function allows the admin to register a new member by hand.
+/**
+ * This function allows the admin to register a new member by hand.
+ * It also allows assigning a primary group to the member being registered.
+ * Accessed by ?action=admin;area=regcenter;sa=register
+ * Requires the moderate_forum permission.
+ *
+ * @uses Register template, admin_register sub-template.
+ */
 function AdminRegister()
 {
 	global $txt, $context, $sourcedir, $scripturl, $smcFunc;
@@ -178,9 +158,18 @@ function AdminRegister()
 		$context['member_groups'] = array();
 }
 
-// I hereby agree not to be a lazy bum.
+/**
+ * Allows the administrator to edit the registration agreement, and choose whether
+ * it should be shown or not. It writes and saves the agreement to the agreement.txt
+ * file.
+ * Accessed by ?action=admin;area=regcenter;sa=agreement.
+ * Requires the admin_forum permission.
+ *
+ * @uses Admin template and the edit_agreement sub template.
+ */
 function EditAgreement()
 {
+	// I hereby agree not to be a lazy bum.
 	global $txt, $boarddir, $context, $modSettings, $smcFunc, $settings;
 
 	// By default we look at agreement.txt.
@@ -226,8 +215,14 @@ function EditAgreement()
 	$context['page_title'] = $txt['registration_agreement'];
 }
 
-// Set reserved names/words....
-function SetReserve()
+/**
+ * Set the names under which users are not allowed to register.
+ * Accessed by ?action=admin;area=regcenter;sa=reservednames.
+ * Requires the admin_forum permission.
+ *
+ * @uses Register template, reserved_words sub-template.
+ */
+function SetReserved()
 {
 	global $txt, $context, $modSettings;
 
@@ -260,7 +255,14 @@ function SetReserve()
 	$context['page_title'] = $txt['admin_reserved_set'];
 }
 
-// This function handles registration settings, and provides a few pretty stats too while it's at it.
+/**
+ * This function handles registration settings, and provides a few pretty stats too while it's at it.
+ * General registration settings and Coppa compliance settings.
+ * Accessed by ?action=admin;area=regcenter;sa=settings.
+ * Requires the admin_forum permission.
+ *
+ * @param $return_config
+ */
 function ModifyRegistrationSettings($return_config = false)
 {
 	global $txt, $context, $scripturl, $modSettings, $sourcedir;

Sources/ManageScheduledTasks.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file concerns itself with scheduled tasks management.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,31 +16,14 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/* /!!!
-
-	void ManageScheduledTasks()
-		// !!!
-
-	void ScheduledTasks()
-		// !!!
-
-	array list_getScheduledTasks()
-		// !!!
-
-	void EditTask()
-		// !!!
-
-	void TaskLog()
-		// !!!
-
-	array list_getTaskLogEntries()
-		// !!!
-
-	array list_getNumTaskLog()
-		// !!!
-*/
-
-// !!!
+/**
+ * Scheduled tasks management dispatcher. This function checks permissions and delegates
+ * to the appropriate function based on the sub-action.
+ * Everything here requires adin_forum permission.
+ *
+ * @uses ManageScheduledTasks template file
+ * @uses ManageScheduledTasks language file
+ */
 function ManageScheduledTasks()
 {
 	global $context, $txt, $modSettings;
@@ -79,7 +64,11 @@ function ManageScheduledTasks()
 	$subActions[$context['sub_action']]();
 }
 
-// List all the scheduled task in place on the forum.
+/**
+ * List all the scheduled task in place on the forum.
+ *
+ * @uses ManageScheduledTasks template, view_scheduled_tasks sub-template
+ */
 function ScheduledTasks()
 {
 	global $context, $txt, $sourcedir, $smcFunc, $user_info, $modSettings, $scripturl;
@@ -275,6 +264,13 @@ function ScheduledTasks()
 	$context['tasks_were_run'] = isset($_GET['done']);
 }
 
+/**
+ * Callback function for createList() in ScheduledTasks().
+ *
+ * @param int $start
+ * @param int $items_per_page
+ * @param string $sort
+ */
 function list_getScheduledTasks($start, $items_per_page, $sort)
 {
 	global $smcFunc, $txt, $scripturl;
@@ -308,7 +304,11 @@ function list_getScheduledTasks($start, $items_per_page, $sort)
 	return $known_tasks;
 }
 
-// Function for editing a task.
+/**
+ * Function for editing a task.
+ *
+ * @uses ManageScheduledTasks template, edit_scheduled_tasks sub-template
+ */
 function EditTask()
 {
 	global $context, $txt, $sourcedir, $smcFunc, $user_info, $modSettings;
@@ -409,7 +409,11 @@ function EditTask()
 	$smcFunc['db_free_result']($request);
 }
 
-// Show the log of all tasks that have taken place.
+/**
+ * Show the log of all tasks that have taken place.
+ *
+ * @uses ManageScheduledTasks language file
+ */
 function TaskLog()
 {
 	global $scripturl, $context, $txt, $smcFunc, $sourcedir;
@@ -513,6 +517,13 @@ function TaskLog()
 	$context['page_title'] = $txt['scheduled_log'];
 }
 
+/**
+ * Callback function for createList() in TaskLog().
+ *
+ * @param int $start
+ * @param int $items_per_page
+ * @param string $sort
+ */
 function list_getTaskLogEntries($start, $items_per_page, $sort)
 {
 	global $smcFunc, $txt;
@@ -539,6 +550,9 @@ function list_getTaskLogEntries($start, $items_per_page, $sort)
 	return $log_entries;
 }
 
+/**
+ * Callback function for createList() in TaskLog().
+ */
 function list_getNumTaskLogEntries()
 {
 	global $smcFunc;

Sources/ManageSearch.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * The admin screen to change the search settings.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,54 +16,17 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/* The admin screen to change the search settings.
-
-	void ManageSearch()
-		- main entry point for the admin search settings screen.
-		- called by ?action=admin;area=managesearch.
-		- requires the admin_forum permission.
-		- loads the ManageSearch template.
-		- loads the Search language file.
-		- calls a function based on the given sub-action.
-		- defaults to sub-action 'settings'.
-
-	void EditSearchSettings()
-		- edit some general settings related to the search function.
-		- called by ?action=admin;area=managesearch;sa=settings.
-		- requires the admin_forum permission.
-		- uses the 'modify_settings' sub template of the ManageSearch template.
-
-	void EditWeights()
-		- edit the relative weight of the search factors.
-		- called by ?action=admin;area=managesearch;sa=weights.
-		- requires the admin_forum permission.
-		- uses the 'modify_weights' sub template of the ManageSearch template.
-
-	void EditSearchMethod()
-		- edit the search method and search index used.
-		- called by ?action=admin;area=managesearch;sa=method.
-		- requires the admin_forum permission.
-		- uses the 'select_search_method' sub template of the ManageSearch
-		  template.
-		- allows to create and delete a fulltext index on the messages table.
-		- allows to delete a custom index (that CreateMessageIndex() created).
-		- calculates the size of the current search indexes in use.
-
-	void CreateMessageIndex()
-		- create a custom search index for the messages table.
-		- called by ?action=admin;area=managesearch;sa=createmsgindex.
-		- linked from the EditSearchMethod screen.
-		- requires the admin_forum permission.
-		- uses the 'create_index', 'create_index_progress', and
-		  'create_index_done' sub templates of the ManageSearch template.
-		- depending on the size of the message table, the process is divided
-		  in steps.
-
-	array loadSearchAPIs()
-		- get the installed APIs.
-
-*/
-
+/**
+ * Main entry point for the admin search settings screen.
+ * It checks permissions, and it forwards to the appropriate function based on
+ * the given sub-action.
+ * Defaults to sub-action 'settings'.
+ * Called by ?action=admin;area=managesearch.
+ * Requires the admin_forum permission.
+ *
+ * @uses ManageSearch template.
+ * @uses Search language file.
+ */
 function ManageSearch()
 {
 	global $context, $txt, $scripturl;
@@ -110,6 +75,14 @@ function ManageSearch()
 	$subActions[$_REQUEST['sa']]();
 }
 
+/**
+ * Edit some general settings related to the search function.
+ * Called by ?action=admin;area=managesearch;sa=settings.
+ * Requires the admin_forum permission.
+ *
+ * @param $return_config
+ * @uses ManageSearch template, 'modify_settings' sub-template.
+ */
 function EditSearchSettings($return_config = false)
 {
 	global $txt, $context, $scripturl, $sourcedir, $modSettings;
@@ -163,6 +136,13 @@ function EditSearchSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
+/**
+ * Edit the relative weight of the search factors.
+ * Called by ?action=admin;area=managesearch;sa=weights.
+ * Requires the admin_forum permission.
+ *
+ * @uses ManageSearch template, 'modify_weights' sub-template.
+ */
 function EditWeights()
 {
 	global $txt, $context, $modSettings;
@@ -198,6 +178,16 @@ function EditWeights()
 		$context['relative_weights'][$factor] = round(100 * (isset($modSettings[$factor]) ? $modSettings[$factor] : 0) / $context['relative_weights']['total'], 1);
 }
 
+/**
+ * Edit the search method and search index used.
+ * Calculates the size of the current search indexes in use.
+ * Allows to create and delete a fulltext index on the messages table.
+ * Allows to delete a custom index (that CreateMessageIndex() created).
+ * Called by ?action=admin;area=managesearch;sa=method.
+ * Requires the admin_forum permission.
+ *
+ * @uses ManageSearch template, 'select_search_method' sub-template.
+ */
 function EditSearchMethod()
 {
 	global $txt, $context, $modSettings, $smcFunc, $db_type, $db_prefix;
@@ -489,6 +479,16 @@ function EditSearchMethod()
 	$context['double_index'] = !empty($context['fulltext_index']) && $context['custom_index'];
 }
 
+/**
+ * Create a custom search index for the messages table.
+ * Called by ?action=admin;area=managesearch;sa=createmsgindex.
+ * Linked from the EditSearchMethod screen.
+ * Requires the admin_forum permission.
+ * Depending on the size of the message table, the process is divided in steps.
+ *
+ * @uses ManageSearch template, 'create_index', 'create_index_progress', and 'create_index_done'
+ *  sub-templates.
+ */
 function CreateMessageIndex()
 {
 	global $modSettings, $context, $smcFunc, $db_prefix, $txt;
@@ -727,7 +727,13 @@ function CreateMessageIndex()
 	}
 }
 
-// Get the installed APIs.
+/**
+ * Get the installed Search API implementations.
+ * This function checks for patterns in comments on top of the Search-API files!
+ * In addition to filenames pattern.
+ * It loads the search API classes if identified.
+ * This function is used by EditSearchMethod to list all installed API implementations.
+ */
 function loadSearchAPIs()
 {
 	global $sourcedir, $txt;

Sources/ManageSearchEngines.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains all the screens that relate to search engines.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,12 +16,9 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains all the screens that relate to search engines.
-
-	// !!!
-*/
-
-// Entry point for this section.
+/**
+ * Entry point for this section.
+ */
 function SearchEngines()
 {
 	global $context, $txt, $scripturl;
@@ -52,7 +51,11 @@ function SearchEngines()
 	$subActions[$context['sub_action']]();
 }
 
-// This is really just the settings page.
+/**
+ * This is really just the settings page.
+ *
+ * @param bool $return_config = false
+ */
 function ManageSearchEngineSettings($return_config = false)
 {
 	global $context, $txt, $modSettings, $scripturl, $sourcedir, $smcFunc;
@@ -134,7 +137,9 @@ function ManageSearchEngineSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
-// View a list of all the spiders we know about.
+/**
+ * View a list of all the spiders we know about.
+ */
 function ViewSpiders()
 {
 	global $context, $txt, $sourcedir, $scripturl, $smcFunc;
@@ -301,6 +306,9 @@ function ViewSpiders()
 	$context['default_list'] = 'spider_list';
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getSpiders($start, $items_per_page, $sort)
 {
 	global $smcFunc;
@@ -321,6 +329,9 @@ function list_getSpiders($start, $items_per_page, $sort)
 	return $spiders;
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getNumSpiders()
 {
 	global $smcFunc;
@@ -337,7 +348,9 @@ function list_getNumSpiders()
 	return $numSpiders;
 }
 
-// Here we can add, and edit, spider info!
+/**
+ * Here we can add, and edit, spider info!
+ */
 function EditSpider()
 {
 	global $context, $smcFunc, $txt;
@@ -429,8 +442,10 @@ function EditSpider()
 
 }
 
-//!!! Should this not be... you know... in a different file?
-// Do we think the current user is a spider?
+/**
+ * Do we think the current user is a spider?
+ * @todo Should this not be... you know... in a different file?
+ */
 function SpiderCheck()
 {
 	global $modSettings, $smcFunc;
@@ -503,8 +518,10 @@ function SpiderCheck()
 	return !empty($_SESSION['id_robot']) ? $_SESSION['id_robot'] : 0;
 }
 
-// Log the spider presence online.
-//!!! Different file?
+/**
+ * Log the spider presence online.
+ * @todo Different file?
+ */
 function logSpider()
 {
 	global $smcFunc, $modSettings, $context;
@@ -564,7 +581,9 @@ function logSpider()
 	}
 }
 
-// This function takes any unprocessed hits and turns them into stats.
+/**
+ * This function takes any unprocessed hits and turns them into stats.
+ */
 function consolidateSpiderStats()
 {
 	global $smcFunc;
@@ -629,7 +648,9 @@ function consolidateSpiderStats()
 	);
 }
 
-// See what spiders have been up to.
+/**
+ * See what spiders have been up to.
+ */
 function SpiderLogs()
 {
 	global $context, $txt, $sourcedir, $scripturl, $smcFunc, $modSettings;
@@ -744,6 +765,9 @@ function SpiderLogs()
 	$context['default_list'] = 'spider_logs';
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getSpiderLogs($start, $items_per_page, $sort)
 {
 	global $smcFunc;
@@ -765,6 +789,9 @@ function list_getSpiderLogs($start, $items_per_page, $sort)
 	return $spider_logs;
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getNumSpiderLogs()
 {
 	global $smcFunc;
@@ -781,7 +808,9 @@ function list_getNumSpiderLogs()
 	return $numLogs;
 }
 
-// Show the spider statistics.
+/**
+ * Show the spider statistics.
+ */
 function SpiderStats()
 {
 	global $context, $txt, $sourcedir, $scripturl, $smcFunc;
@@ -932,6 +961,9 @@ function SpiderStats()
 	$context['default_list'] = 'spider_stat_list';
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getSpiderStats($start, $items_per_page, $sort)
 {
 	global $smcFunc;
@@ -953,6 +985,9 @@ function list_getSpiderStats($start, $items_per_page, $sort)
 	return $spider_stats;
 }
 
+/**
+ * Callback function for createList()
+ */
 function list_getNumSpiderStats()
 {
 	global $smcFunc;
@@ -969,7 +1004,9 @@ function list_getNumSpiderStats()
 	return $numStats;
 }
 
-// Recache spider names?
+/**
+ * Recache spider names?
+ */
 function recacheSpiderNames()
 {
 	global $smcFunc;
@@ -988,7 +1025,9 @@ function recacheSpiderNames()
 	updateSettings(array('spider_name_cache' => serialize($spiders)));
 }
 
-// Sort the search engine table by user agent name to avoid misidentification of engine.
+/**
+ * Sort the search engine table by user agent name to avoid misidentification of engine.
+ */
 function sortSpiderTable()
 {
 	global $smcFunc;

Sources/Who.php

@@ -1,6 +1,9 @@
 <?php
 
 /**
+ * This file is mainly concerned with the Who's Online list.
+ * Although, it also handles credits. :P
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,44 +17,16 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file is mainly concerned, or that is to say only concerned, with the
-	Who's Online list.  It contains only the following functions:
-
-	void Who()
-		- prepares the who's online data for the Who template.
-		- uses the Who template (main sub template.) and language file.
-		- requires the who_view permission.
-		- is enabled with the who_enabled setting.
-		- is accessed via ?action=who.
-
-	array determineActions(array urls, string preferred_prefix = false)
-		- determine the actions of the members passed in urls.
-		- urls should be a single url (string) or an array of arrays, each
-		  inner array being (serialized request data, id_member).
-		- returns an array of descriptions if you passed an array, otherwise
-		  the string describing their current location.
-
-	void Credits(bool in_admin)
-		- prepares credit and copyright information for the credits page or the admin page
-		- if parameter is true the it will not load the sub template nor the template file
-
-	Adding actions to the Who's Online list:
-	---------------------------------------------------------------------------
-		Adding actions to this list is actually relatively easy....
-		- for actions anyone should be able to see, just add a string named
-		   whoall_ACTION.  (where ACTION is the action used in index.php.)
-		- for actions that have a subaction which should be represented
-		   differently, use whoall_ACTION_SUBACTION.
-		- for actions that include a topic, and should be restricted, use
-		   whotopic_ACTION.
-		- for actions that use a message, by msg or quote, use whopost_ACTION.
-		- for administrator-only actions, use whoadmin_ACTION.
-		- for actions that should be viewable only with certain permissions,
-		   use whoallow_ACTION and add a list of possible permissions to the
-		   $allowedActions array, using ACTION as the key.
-*/
-
-// Who's online, and what are they doing?
+/**
+ * Who's online, and what are they doing?
+ * This function prepares the who's online data for the Who template.
+ * It requires the who_view permission.
+ * It is enabled with the who_enabled setting.
+ * It is accessed via ?action=who.
+ *
+ * @uses Who template, main sub-template
+ * @uses Who language file.
+ */
 function Who()
 {
 	global $context, $scripturl, $user_info, $txt, $modSettings, $memberContext, $smcFunc;
@@ -266,6 +241,29 @@ function Who()
 
 }
 
+/**
+ * This function determines the actions of the members passed in urls.
+ *
+ * Adding actions to the Who's Online list:
+ * Adding actions to this list is actually relatively easy...
+ *  - for actions anyone should be able to see, just add a string named
+ *   whoall_ACTION.  (where ACTION is the action used in index.php.)
+ *  - for actions that have a subaction which should be represented
+ *   differently, use whoall_ACTION_SUBACTION.
+ *  - for actions that include a topic, and should be restricted, use
+ *   whotopic_ACTION.
+ *  - for actions that use a message, by msg or quote, use whopost_ACTION.
+ *  - for administrator-only actions, use whoadmin_ACTION.
+ *  - for actions that should be viewable only with certain permissions,
+ *   use whoallow_ACTION and add a list of possible permissions to the
+ *   $allowedActions array, using ACTION as the key.
+ *
+ * @param mixed $urls, a single url (string) or an array of arrays, each
+ * inner array being (serialized request data, id_member)
+ * @param string $preferred_prefix = false
+ * @return array, an array of descriptions if you passed an array, otherwise
+ * the string describing their current location.
+ */
 function determineActions($urls, $preferred_prefix = false)
 {
 	global $txt, $user_info, $modSettings, $smcFunc, $context;
@@ -275,6 +273,7 @@ function determineActions($urls, $preferred_prefix = false)
 	loadLanguage('Who');
 
 	// Actions that require a specific permission level.
+	// @todo are these actions still available
 	$allowedActions = array(
 		'admin' => array('moderate_forum', 'manage_membergroups', 'manage_bans', 'admin_forum', 'manage_permissions', 'send_mail', 'manage_attachments', 'manage_smileys', 'manage_boards', 'edit_news'),
 		'ban' => array('manage_bans'),
@@ -513,6 +512,11 @@ function determineActions($urls, $preferred_prefix = false)
 		return $data;
 }
 
+/**
+ * It prepares credit and copyright information for the credits page or the admin page
+ *
+ * @param $in_admin = false, if parameter is true the it will not load the sub-template nor the template file
+ */
 function Credits($in_admin = false)
 {
 	global $context, $modSettings, $forum_copyright, $forum_version, $boardurl, $txt, $user_info;