! Some more documentation changes

! Small template issue on split topic screen fixed by Runic [4888]. @todo fix in 2.0 branch
+ Added some functions to keep JS & CSS files together. Next step is to make use of them
! Changed template_button_strip() to have a blank default instead of using top as the default
- Loadfile

Sources/Errors.php

@@ -359,7 +359,7 @@ function display_maintenance_message()
  */
 function display_db_error()
 {
-	global $sourcedir, $mbname, $modSettings;
+	global $mbname, $modSettings, $maintenance;
 	global $db_connection, $webmaster_email, $db_last_error, $db_error_send, $smcFunc;
 
 	set_fatal_error_headers();

Sources/Load.php

@@ -202,12 +202,12 @@ function reloadSettings()
  * Load all the important user information.
  * What it does:
  * 	- sets up the $user_info array
- *	- assigns $user_info['query_wanna_see_board'] for what boards the user can see.
- *	- first checks for cookie or integration validation.
- *	- uses the current session if no integration function or cookie is found.
- *	- checks password length, if member is activated and the login span isn't over.
- *		- if validation fails for the user, $id_member is set to 0.
- *		- updates the last visit time when needed.
+ * 	- assigns $user_info['query_wanna_see_board'] for what boards the user can see.
+ * 	- first checks for cookie or integration validation.
+ * 	- uses the current session if no integration function or cookie is found.
+ * 	- checks password length, if member is activated and the login span isn't over.
+ * 		- if validation fails for the user, $id_member is set to 0.
+ * 		- updates the last visit time when needed.
  */
 function loadUserSettings()
 {
@@ -245,9 +245,7 @@ function loadUserSettings()
 	}
 	elseif (empty($id_member) && isset($_SESSION['login_' . $cookiename]) && ($_SESSION['USER_AGENT'] == $_SERVER['HTTP_USER_AGENT'] || !empty($modSettings['disableCheckUA'])))
 	{
-		/*
-		 * @todo Perhaps we can do some more checking on this, such as on the first octet of the IP?
-		 */
+		 // @todo Perhaps we can do some more checking on this, such as on the first octet of the IP?
 		list ($id_member, $password, $login_span) = @unserialize($_SESSION['login_' . $cookiename]);
 		$id_member = !empty($id_member) && strlen($password) == 40 && $login_span > time() ? (int) $id_member : 0;
 	}
@@ -311,6 +309,7 @@ function loadUserSettings()
 		// 4. New session, yet updated < five hours ago? Maybe cache can help.
 		if (SMF != 'SSI' && !isset($_REQUEST['xml']) && (!isset($_REQUEST['action']) || $_REQUEST['action'] != '.xml') && empty($_SESSION['id_msg_last_visit']) && (empty($modSettings['cache_enable']) || ($_SESSION['id_msg_last_visit'] = cache_get_data('user_last_visit-' . $id_member, 5 * 3600)) === null))
 		{
+			// @todo can this be cached?
 			// Do a quick query to make sure this isn't a mistake.
 			$result = $smcFunc['db_query']('', '
 				SELECT poster_time
@@ -627,6 +626,8 @@ function loadBoard()
 				// Free the previous result
 				$smcFunc['db_free_result']($request);
 
+				// @todo why is this using id_topic?
+				// @todo Can this get cached?
 				$request = $smcFunc['db_query']('', '
 					SELECT COUNT(id_topic)
 					FROM {db_prefix}topics
@@ -854,6 +855,7 @@ function loadPermissions()
  * @param mixed $users An array of users by id or name
  * @param bool $is_name = false $users is by name or by id
  * @param string $set = 'normal' What kind of data to load (normal, profile, minimal)
+ * @return array|bool The ids of the members loaded or false
  */
 function loadMemberData($users, $is_name = false, $set = 'normal')
 {
@@ -1725,15 +1727,13 @@ function loadTheme($id_theme = 0, $initialize = true)
 /**
  * Load a template - if the theme doesn't include it, use the default.
  * What this function does:
- * - loads a template file with the name template_name from the current, default,
- *  or base theme.
- *  - uses the template_include() function to include the file.
- *  - detects a wrong default theme directory and tries to work around it.
- *  - if fatal is true, dies with an error message if the template cannot be found.
- *
+ * * loads a template file with the name template_name from the current, default, or base theme.
+ * * detects a wrong default theme directory and tries to work around it.
+ * 
+ * @uses the template_include() function to include the file.
  * @param string $template_name
  * @param array $style_sheets = array()
- * @param bool $fatal = true
+ * @param bool $fatal = true if fatal is true, dies with an error message if the template cannot be found
  * @return bool
  */
 function loadTemplate($template_name, $style_sheets = array(), $fatal = true)
@@ -1855,7 +1855,37 @@ function loadSubTemplate($sub_template_name, $fatal = false)
 }
 
 /**
- *  Load a language file.  Tries the current and default themes as well as the user and global languages.
+ * Add a CSS file for output later
+ * @param string $filename
+ * @param array $options
+ */
+function loadCSSFile($filename, $options = array())
+{
+	global $settings, $context;
+
+	if (strpos($filename, 'http://') === false || !empty($options['local']))
+		$filename = $settings['theme_url'] . '/' . $filename;
+
+	$context['css_files'][$filename] = $options;
+}
+
+/**
+ * Add a CSS file for output later
+ * @param string $filename
+ * @param array $options
+ */
+function loadJavascriptFile($filename, $options = array())
+{
+	global $settings, $context;
+
+	if (strpos($filename, 'http://') === false || !empty($options['local']))
+		$filename = $settings['theme_url'] . '/' . $filename;
+
+	$context['javascript_files'][$filename] = $options;
+}
+
+/**
+ * Load a language file.  Tries the current and default themes as well as the user and global languages.
  *
  * @param string $template_name
  * @param string $lang

Sources/LogInOut.php

@@ -624,7 +624,6 @@ function md5_hmac($data, $key)
 	return md5(($key ^ str_repeat(chr(0x5c), 64)) . pack('H*', md5(($key ^ str_repeat(chr(0x36), 64)) . $data)));
 }
 
-// Special encryption used by phpBB3.
 /**
  * Custom encryption for phpBB3 based passwords.
  *

Sources/Logging.php

@@ -451,6 +451,7 @@ function logAction($action, $extra = array(), $log_type = 'moderate')
 	else
 		$msg_id = '0';
 
+	// @todo cache this?
 	// Is there an associated report on this?
 	if (in_array($action, array('move', 'remove', 'split', 'merge')))
 	{

Sources/ManageAttachments.php

@@ -157,7 +157,7 @@ function ManageAttachmentSettings($return_config = false)
  * Show/set permissions for permissions: 'profile_server_avatar',
  * 	'profile_upload_avatar' and 'profile_remote_avatar'.
  *
- * @param $return_config
+ * @param bool $return_config = false
  * @uses 'avatars' sub template.
  */
 function ManageAvatarSettings($return_config = false)

Sources/ManageBoards.php

@@ -361,18 +361,17 @@ function EditCategory2()
 
 /**
  * Modify a specific board...
- * 	void EditBoard()
-		- screen for editing and repositioning a board.
-		- called by ?action=admin;area=manageboards;sa=board
-		- uses the modify_board sub-template of the ManageBoards template.
-		- requires manage_boards permission.
-		- also used to show the confirm deletion of category screen
+ * screen for editing and repositioning a board.
+ * called by ?action=admin;area=manageboards;sa=board
+ * uses the modify_board sub-template of the ManageBoards template.
+ * requires manage_boards permission.
+ * also used to show the confirm deletion of category screen (sub-template confirm_board_delete).
 		  (sub-template confirm_board_delete).
 
  */
 function EditBoard()
 {
-	global $txt, $context, $cat_tree, $boards, $boardList, $sourcedir, $smcFunc, $modSettings;
+	global $txt, $context, $cat_tree, $boards, $boardList, $smcFunc, $modSettings;
 
 	loadTemplate('ManageBoards');
 	require_once($sourcedir . '/Subs-Boards.php');

Sources/ManageLanguages.php

@@ -760,7 +760,6 @@ function ModifyLanguageSettings($return_config = false)
 
 /**
  * Edit a particular set of language entries.
- *
  */
 function ModifyLanguage()
 {

Sources/ManageMembergroups.php

@@ -336,9 +336,7 @@ function AddMembergroup()
 		$postCountBasedGroup = isset($_POST['min_posts']) && (!isset($_POST['postgroup_based']) || !empty($_POST['postgroup_based']));
 		$_POST['group_type'] = !isset($_POST['group_type']) || $_POST['group_type'] < 0 || $_POST['group_type'] > 3 || ($_POST['group_type'] == 1 && !allowedTo('admin_forum')) ? 0 : (int) $_POST['group_type'];
 
-		/**
-		 * @todo Check for members with same name too?
-		 */
+		// @todo Check for members with same name too?
 
 		$request = $smcFunc['db_query']('', '
 			SELECT MAX(id_group)

Sources/ManageNews.php

@@ -771,7 +771,7 @@ function SendMailing($clean_only = false)
  * Requires the forum_admin permission.
  *
  * @uses ManageNews template, news_settings sub-template.
- * @param $return_config
+ * @param bool $return_config = false
  */
 function ModifyNewsSettings($return_config = false)
 {

Sources/ManagePosts.php

@@ -170,7 +170,7 @@ function SetCensor()
  * Requires the admin_forum permission.
  * Accessed from ?action=admin;area=postsettings;sa=posts.
  *
- * @param $return_config
+ * @param bool $return_config = false
  * @uses Admin template, edit_post_settings sub-template.
  */
 function ModifyPostSettings($return_config = false)
@@ -333,7 +333,7 @@ function ModifyBBCSettings($return_config = false)
  * Requires the admin_forum permission.
  * Accessed from ?action=admin;area=postsettings;sa=topics.
 
- * @param $return_config
+ * @param bool $return_config = false
  * @uses Admin template, edit_topic_settings sub-template.
  */
 function ModifyTopicSettings($return_config = false)

Sources/ManageRegistration.php

@@ -269,7 +269,7 @@ function SetReserved()
  * Accessed by ?action=admin;area=regcenter;sa=settings.
  * Requires the admin_forum permission.
  *
- * @param $return_config
+ * @param bool $return_config = false
  */
 function ModifyRegistrationSettings($return_config = false)
 {

Sources/ManageSettings.php

@@ -20,8 +20,8 @@ if (!defined('SMF'))
 /**
  * This just avoids some repetition.
  *
- * @param $subActions
- * @param $defaultAction
+ * @param array $subActions = array()
+ * @param string $defaultAction = ''
  */
 function loadGeneralSettingParameters($subActions = array(), $defaultAction = '')
 {

Sources/PackageGet.php

@@ -626,9 +626,7 @@ function PackageUpload()
 	// Setup the correct template, even though I'll admit we ain't downloading ;)
 	$context['sub_template'] = 'downloaded';
 
-	/**
-	 * @todo Use FTP if the Packages directory is not writable.
-	 */
+	// @todo Use FTP if the Packages directory is not writable.
 
 	// Check the file was even sent!
 	if (!isset($_FILES['package']['name']) || $_FILES['package']['name'] == '')
@@ -647,9 +645,7 @@ function PackageUpload()
 
 	// Setup the destination and throw an error if the file is already there!
 	$destination = $boarddir . '/Packages/' . $packageName;
-	/**
-	 * @todo Maybe just roll it like we do for downloads?
-	 */
+	// @todo Maybe just roll it like we do for downloads?
 	if (file_exists($destination))
 		fatal_lang_error('package_upload_error_exists');
 

Sources/PersonalMessage.php

@@ -635,9 +635,7 @@ function MessageFolder()
 	// This is kinda simple!
 	else
 	{
-		/**
-		 * @todo SLOW This query uses a filesort. (inbox only.)
-		 */
+		// @todo SLOW This query uses a filesort. (inbox only.)
 		$request = $smcFunc['db_query']('', '
 			SELECT pm.id_pm, pm.id_pm_head, pm.id_member_from
 			FROM {db_prefix}personal_messages AS pm' . ($context['folder'] == 'sent' ? '' . ($context['sort_by'] == 'name' ? '
@@ -1168,9 +1166,7 @@ function MessageSearch2()
 	}
 
 	// Setup the sorting variables...
-	/**
-	 * @todo Add more in here!
-	 */
+	// @todo Add more in here!
 	$sort_columns = array(
 		'pm.id_pm',
 	);
@@ -2434,9 +2430,7 @@ function MessageActionsApply()
 		$smcFunc['db_free_result']($request);
 
 		// Any errors?
-		/**
-		 * @todo Separate the sprintf?
-		 */
+		// @todo Separate the sprintf?
 		if (!empty($updateErrors))
 			fatal_lang_error('labels_too_many', true, array($updateErrors));
 	}
@@ -3056,9 +3050,7 @@ function ReportMessage()
 	{
 		$context['sub_template'] = 'report_message';
 
-		/**
-		 * @todo I don't like being able to pick who to send it to.  Favoritism, etc. sucks.
-		 */
+		// @todo I don't like being able to pick who to send it to.  Favoritism, etc. sucks.
 		// Now, get all the administrators.
 		$request = $smcFunc['db_query']('', '
 			SELECT id_member, real_name
@@ -3448,9 +3440,7 @@ function ApplyRules($all_messages = false)
 	// Just unread ones?
 	$ruleQuery = $all_messages ? '' : ' AND pmr.is_new = 1';
 
-	/**
-	 * @todo Apply all should have timeout protection!
-	 */
+	// @todo Apply all should have timeout protection!
 	// Get all the messages that match this.
 	$request = $smcFunc['db_query']('', '
 		SELECT

Sources/Profile-View.php

@@ -957,6 +957,7 @@ function trackActivity($memID)
 	require_once($sourcedir . '/Subs-List.php');
 	createList($listOptions);
 
+	// @todo cache this
 	// If this is a big forum, or a large posting user, let's limit the search.
 	if ($modSettings['totalMessages'] > 50000 && $user_profile[$memID]['posts'] > 500)
 	{
@@ -981,6 +982,7 @@ function trackActivity($memID)
 		$user_profile[$memID]['member_ip2'],
 	);
 
+	// @todo cache this
 	// Get all IP addresses this user has used for his messages.
 	$request = $smcFunc['db_query']('', '
 		SELECT poster_ip

Sources/Subs-Auth.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file has functions in it to do with authentication, user handling, and the like.
+ * 
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,92 +16,16 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file has functions in it to do with authentication, user handling,
-	and the like.  It provides these functions:
-
-	void setLoginCookie(int cookie_length, int id_member, string password = '')
-		- sets the SMF-style login cookie and session based on the id_member
-		  and password passed.
-		- password should be already encrypted with the cookie salt.
-		- logs the user out if id_member is zero.
-		- sets the cookie and session to last the number of seconds specified
-		  by cookie_length.
-		- when logging out, if the globalCookies setting is enabled, attempts
-		  to clear the subdomain's cookie too.
-
-	array url_parts(bool local, bool global)
-		- returns the path and domain to set the cookie on.
-		- normally, local and global should be the localCookies and
-		  globalCookies settings, respectively.
-		- uses boardurl to determine these two things.
-		- returns an array with domain and path in it, in that order.
-
-	void KickGuest()
-		- throws guests out to the login screen when guest access is off.
-		- sets $_SESSION['login_url'] to $_SERVER['REQUEST_URL'].
-		- uses the 'kick_guest' sub template found in Login.template.php.
-
-	void InMaintenance()
-		- display a message about being in maintenance mode.
-		- display a login screen with sub template 'maintenance'.
-
-	void adminLogin()
-		- double check the verity of the admin by asking for his or her
-		  password.
-		- loads Login.template.php and uses the admin_login sub template.
-		- sends data to template so the admin is sent on to the page they
-		  wanted if their password is correct, otherwise they can try
-		  again.
-
-	string adminLogin_outputPostVars(string key, string value)
-		- used by the adminLogin() function.
-		- returns 'hidden' HTML form fields, containing key-value-pairs.
-		- if 'value' is an array, the function is called recursively.
-
-	array findMembers(array names, bool use_wildcards = false,
-			bool buddies_only = false, int max = 500)
-		- searches for members whose username, display name, or e-mail address
-		  match the given pattern of array names.
-		- accepts wildcards ? and * in the patern if use_wildcards is set.
-		- retrieves a maximum of max members, if passed.
-		- searches only buddies if buddies_only is set.
-		- returns an array containing information about the matching members.
-
-	void JSMembers()
-		- called by index.php?action=findmember.
-		- is used as a popup for searching members.
-		- uses sub template find_members of the Help template.
-		- also used to add members for PM's sent using wap2/imode protocol.
-
-	void RequestMembers()
-		- used by javascript to find members matching the request.
-		- outputs each member name on its own line.
-
-	void resetPassword(int id_member, string username = null)
-		- called by Profile.php when changing someone's username.
-		- checks the validity of the new username.
-		- generates and sets a new password for the given user.
-		- mails the new password to the email address of the user.
-		- if username is not set, only a new password is generated and sent.
-
-	string validateUsername(int memID, string username)
-		- checks a username obeys a load of rules. Returns null if fine.
-
-	string validatePassword(string password, string username,
-			array restrict_in = none)
-		- called when registering/choosing a password.
-		- checks the password obeys the current forum settings for password
-		  strength.
-		- if password checking is enabled, will check that none of the words
-		  in restrict_in appear in the password.
-		- returns an error identifier if the password is invalid, or null.
-
-	void rebuildModCache()
-		- stores some useful information on the current users moderation powers in the session.
-
-*/
-
-// Actually set the login cookie...
+/**
+ * sets the SMF-style login cookie and session based on the id_member and password passed.
+ * password should be already encrypted with the cookie salt.
+ * logs the user out if id_member is zero.
+ * sets the cookie and session to last the number of seconds specified by cookie_length.
+ * when logging out, if the globalCookies setting is enabled, attempts to clear the subdomain's cookie too.
+ * @param int $cookie_length, 
+ * @param int $id The id of the member 
+ * @param string $password = ''
+ */
 function setLoginCookie($cookie_length, $id, $password = '')
 {
 	global $cookiename, $boardurl, $modSettings, $sourcedir;
@@ -184,13 +110,21 @@ function setLoginCookie($cookie_length, $id, $password = '')
 	}
 }
 
+// @todo remove this? wouldn't it get caught earlier?
 // PHP < 4.3.2 doesn't have this function
 if (!function_exists('session_regenerate_id'))
 {
 	require_once $sourcedir . 'Subs-Compat.php';
 }
 
-// Get the domain and path for the cookie...
+/**
+ * Get the domain and path for the cookie
+ * normally, local and global should be the localCookies and globalCookies settings, respectively.
+ * uses boardurl to determine these two things.
+ * @param bool $local, 
+ * @param bool $global
+ * @return array an array to set the cookie on with domain and path in it, in that order
+ */
 function url_parts($local, $global)
 {
 	global $boardurl;
@@ -217,7 +151,11 @@ function url_parts($local, $global)
 	return array($parsed_url['host'], $parsed_url['path'] . '/');
 }
 
-// Kick out a guest when guest access is off...
+/**
+ * Throws guests out to the login screen when guest access is off.
+ * sets $_SESSION['login_url'] to $_SERVER['REQUEST_URL'].
+ * uses the 'kick_guest' sub template found in Login.template.php.
+ */
 function KickGuest()
 {
 	global $txt, $context;
@@ -233,7 +171,10 @@ function KickGuest()
 	$context['page_title'] = $txt['login'];
 }
 
-// Display a message about the forum being in maintenance mode, etc.
+/**
+ * Display a message about being in maintenance mode.
+ * display a login screen with sub template 'maintenance'.
+ */
 function InMaintenance()
 {
 	global $txt, $mtitle, $mmessage, $context;
@@ -251,6 +192,13 @@ function InMaintenance()
 	$context['page_title'] = $txt['maintain_mode'];
 }
 
+/**
+ * Double check the verity of the admin by asking for his or her password.
+ * loads Login.template.php and uses the admin_login sub template.
+ * sends data to template so the admin is sent on to the page they
+ *  wanted if their password is correct, otherwise they can try again.
+ * @param string $type = 'admin'
+ */
 function adminLogin($type = 'admin')
 {
 	global $context, $scripturl, $txt, $user_info, $user_settings;
@@ -304,6 +252,13 @@ function adminLogin($type = 'admin')
 	trigger_error('Hacking attempt...', E_USER_ERROR);
 }
 
+/**
+ * used by the adminLogin() function.
+ * if 'value' is an array, the function is called recursively.
+ * @param string $key
+ * @param string $value
+ * @return string 'hidden' HTML form fields, containing key-value-pairs
+ */
 function adminLogin_outputPostVars($k, $v)
 {
 	global $smcFunc;
@@ -355,6 +310,15 @@ function construct_query_string($get)
 }
 
 // Find members by email address, username, or real name.
+/**
+ * searches for members whose username, display name, or e-mail address match the given pattern of array names.
+ * searches only buddies if buddies_only is set.
+ * @param array $names, 
+ * @param bool $use_wildcards = false, accepts wildcards ? and * in the patern if true
+ * @param bool $buddies_only = false, 
+ * @param int $max = 500 retrieves a maximum of max members, if passed
+ * @return array containing information about the matching members
+ */
 function findMembers($names, $use_wildcards = false, $buddies_only = false, $max = 500)
 {
 	global $scripturl, $user_info, $modSettings, $smcFunc;
@@ -431,6 +395,12 @@ function findMembers($names, $use_wildcards = false, $buddies_only = false, $max
 	return $results;
 }
 
+/**
+ * called by index.php?action=findmember.
+ * is used as a popup for searching members.
+ * uses sub template find_members of the Help template.
+ * also used to add members for PM's sent using wap2/imode protocol.
+ */
 function JSMembers()
 {
 	global $context, $scripturl, $user_info, $smcFunc;
@@ -497,6 +467,10 @@ function JSMembers()
 		$context['links']['up'] = $scripturl . '?action=pm;sa=send' . (empty($_REQUEST['u']) ? '' : ';u=' . $_REQUEST['u']);
 }
 
+/**
+ * outputs each member name on its own line.
+ * used by javascript to find members matching the request.
+ */
 function RequestMembers()
 {
 	global $user_info, $txt, $smcFunc;
@@ -555,7 +529,16 @@ function RequestMembers()
 	obExit(false);
 }
 
-// This function generates a random password for a user and emails it to them.
+/**
+ * Generates a random password for a user and emails it to them.
+ * called by Profile.php when changing someone's username.
+ * checks the validity of the new username.
+ * generates and sets a new password for the given user.
+ * mails the new password to the email address of the user.
+ * if username is not set, only a new password is generated and sent.
+ * @param int $memID
+ * @param string $username = null
+ */
 function resetPassword($memID, $username = null)
 {
 	global $scripturl, $context, $txt, $sourcedir, $modSettings, $smcFunc, $language;
@@ -610,7 +593,12 @@ function resetPassword($memID, $username = null)
 	sendmail($email, $emaildata['subject'], $emaildata['body'], null, null, false, 0);
 }
 
-// Is this a valid username?
+/**
+ * Checks a username obeys a load of rules
+ * @param int $memID, 
+ * @param string $username
+ * @return string Returns null if fine
+ */
 function validateUsername($memID, $username)
 {
 	global $sourcedir, $txt;
@@ -633,7 +621,17 @@ function validateUsername($memID, $username)
 	return null;
 }
 
-// This function simply checks whether a password meets the current forum rules.
+/**
+ * Checks whether a password meets the current forum rules
+ * called when registering/choosing a password.
+ * checks the password obeys the current forum settings for password strength.
+ * if password checking is enabled, will check that none of the words in restrict_in appear in the password.
+ * returns an error identifier if the password is invalid, or null.
+ * @param string $password
+ * @param string $username
+ * @param array $restrict_in = array()
+ * @return string an error identifier if the password is invalid
+ */
 function validatePassword($password, $username, $restrict_in = array())
 {
 	global $modSettings, $smcFunc;
@@ -665,7 +663,10 @@ function validatePassword($password, $username, $restrict_in = array())
 	return $good ? null : 'chars';
 }
 
-// Quickly find out what this user can and cannot do.
+/**
+ * Quickly find out what this user can and cannot do.
+ * stores some useful information on the current users moderation powers in the session.
+ */
 function rebuildModCache()
 {
 	global $user_info, $smcFunc;

Sources/Subs-Calendar.php

@@ -1,8 +1,7 @@
 <?php
 
 /**
- * This file contains several functions for retrieving and manipulating
- *  calendar events, birthdays and holidays.
+ * This file contains several functions for retrieving and manipulating calendar events, birthdays and holidays.
  * 
  * Simple Machines Forum (SMF)
  *
@@ -17,65 +16,33 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	
-
- array getCalendarGrid(int month, int year, array calendarOptions)
- * returns an array containing all the information needed to show a
- *  calendar grid for the given month.
- * also provides information (link, month, year) about the previous and
- *  next month.
-
- array getCalendarWeek(int month, int year, int day, array calendarOptions)
- * as for getCalendarGrid but provides information relating to the week
- *  within which the passed date sits.
-
- array cache_getOffsetIndependentEvents(int days_to_index)
- * cache callback function used to retrieve the birthdays, holidays, and
- *  events between now and now + days_to_index.
- * widens the search range by an extra 24 hours to support time offset
- *  shifts.
- * used by the cache_getRecentEvents function to get the information
- *  needed to calculate the events taking the users time offset into
- *  account.
-
- array cache_getRecentEvents(array eventOptions)
- * cache callback function used to retrieve the upcoming birthdays,
- *  holidays, and events within the given period, taking into account
- *  the users time offset.
- * used by the board index and SSI to show the upcoming events.
-
- void validateEventPost()
- * checks if the calendar post was valid.
-
- int getEventPoster(int event_id)
- * gets the member_id of an event identified by event_id.
- * returns false if the event was not found.
-
- void insertEvent(array eventOptions)
+/**
+ void insertEvent(
  * inserts the passed event information into the calendar table.
  * allows to either set a time span (in days) or an end_date.
  * does not check any permissions of any sort.
+ * @param array $eventOptions
 
- void modifyEvent(int event_id, array eventOptions)
+ void modifyEvent(
  * modifies an event.
  * allows to either set a time span (in days) or an end_date.
  * does not check any permissions of any sort.
+ * @param int $event_id
+ * @param array $eventOptions
 
- void removeEvent(int event_id)
+ void removeEvent(
  * removes an event.
  * does no permission checks.
+ * @param int $event_id
 */
 
 /** 
  * Get all birthdays within the given time range.
- * array getBirthdayRange(string earliest_date, string latest_date)
  * finds all the birthdays in the specified range of days.
- * earliest_date and latest_date are inclusive, and should both be in
- *  the YYYY-MM-DD format.
- * works with birthdays set for no year, or any other year, and
- *  respects month and year boundaries.
- * returns an array of days, each of which an array of birthday
- *  information for the context.
+ * works with birthdays set for no year, or any other year, and respects month and year boundaries.
+ * @param string $low_date inclusive, YYYY-MM-DD
+ * @param string $high_date inclusive, YYYY-MM-DD
+ * @return array days, each of which an array of birthday information for the context
  */
 function getBirthdayRange($low_date, $high_date)
 {
@@ -136,16 +103,14 @@ function getBirthdayRange($low_date, $high_date)
 
 /**
  * Get all events within the given time range.
- * array getEventRange(string earliest_date, string latest_date,
-			bool use_permissions = true)
-		- finds all the posted calendar events within a date range.
-		- both the earliest_date and latest_date should be in the standard
-		  YYYY-MM-DD format.
-		- censors the posted event titles.
-		- uses the current user's permissions if use_permissions is true,
-		  otherwise it does nothing "permission specific".
-		- returns an array of contextual information if use_permissions is
-		  true, and an array of the data needed to build that otherwise.
+ * finds all the posted calendar events within a date range.
+ * both the earliest_date and latest_date should be in the standard YYYY-MM-DD format.
+ * censors the posted event titles.
+ * uses the current user's permissions if use_permissions is true, otherwise it does nothing "permission specific"
+ * @param string $earliest_date
+ * @param string $latest_date
+ * @param bool $use_permissions = true
+ * @return array contextual information if use_permissions is true, and an array of the data needed to build that otherwise
  */
 function getEventRange($low_date, $high_date, $use_permissions = true)
 {
@@ -245,11 +210,8 @@ function getEventRange($low_date, $high_date, $use_permissions = true)
 
 /**
  * Get all holidays within the given time range.
- * 
- * $low_date and $high_date should be YYYY-MM-DD.
- * 
- * @param string $low_date
- * @param string $high_date
+ * @param string $low_date YYYY-MM-DD
+ * @param string $high_date YYYY-MM-DD
  * @return array an array of days, which are all arrays of holiday names.
  */
 function getHolidayRange($low_date, $high_date)
@@ -293,13 +255,10 @@ function getHolidayRange($low_date, $high_date)
 	return $holidays;
 }
 
-// Does permission checks to see if an event can be linked to a board/topic.
 /**
- *  void canLinkEvent()
- * checks if the current user can link the current topic to the
- *  calendar, permissions et al.
- * this requires the calendar_post permission, a forum moderator, or a
- *  topic starter.
+ * Does permission checks to see if an event can be linked to a board/topic.
+ * checks if the current user can link the current topic to the calendar, permissions et al.
+ * this requires the calendar_post permission, a forum moderator, or a topic starter.
  * expects the $topic and $board variables to be set.
  * if the user doesn't have proper permissions, an error will be shown.
  */
@@ -342,9 +301,8 @@ function canLinkEvent()
 	}
 }
 
-// Returns date information about 'today' relative to the users time offset.
 /**
- * array getTodayInfo()
+ * Returns date information about 'today' relative to the users time offset.
  * returns an array with the current date, day, month, and year.
  * takes the users time offset into account.
  */
@@ -359,11 +317,11 @@ function getTodayInfo()
 }
 
 /**
- * Returns the information needed to show a calendar grid for the given month.
- * 
+ * Provides information (link, month, year) about the previous and next month.
  * @param int $month
  * @param int $year
  * @param array $calendarOptions
+ * @return array containing all the information needed to show a calendar grid for the given month
  */
 function getCalendarGrid($month, $year, $calendarOptions)
 {
@@ -520,6 +478,7 @@ function getCalendarGrid($month, $year, $calendarOptions)
  * @param int $year
  * @param int $day
  * @param array $calendarOptions
+ * @return array
  */
 function getCalendarWeek($month, $year, $day, $calendarOptions)
 {
@@ -640,11 +599,13 @@ function getCalendarWeek($month, $year, $day, $calendarOptions)
 	return $calendarGrid;
 }
 
-// 
 /**
  * Retrieve all events for the given days, independently of the users offset.
- * 
+ * cache callback function used to retrieve the birthdays, holidays, and events between now and now + days_to_index.
+ * widens the search range by an extra 24 hours to support time offset shifts.
+ * used by the cache_getRecentEvents function to get the information needed to calculate the events taking the users time offset into account.
  * @param int $days_to_index
+ * @return array
  */
 function cache_getOffsetIndependentEvents($days_to_index)
 {
@@ -664,11 +625,12 @@ function cache_getOffsetIndependentEvents($days_to_index)
 	);
 }
 
-// Called from the BoardIndex to display the current day's events on the board index.
 /**
- * 
- * Enter description here ...
+ * cache callback function used to retrieve the upcoming birthdays, holidays, and events within the given period, taking into account the users time offset.
+ * Called from the BoardIndex to display the current day's events on the board index
+ * used by the board index and SSI to show the upcoming events.
  * @param array $eventOptions
+ * @return array
  */
 function cache_getRecentEvents($eventOptions)
 {
@@ -785,10 +747,8 @@ function cache_getRecentEvents($eventOptions)
 	);
 }
 
-// Makes sure the calendar post is valid.
 /**
- * 
- * Enter description here ...
+ * Makes sure the calendar post is valid.
  */
 function validateEventPost()
 {
@@ -849,6 +809,7 @@ function validateEventPost()
  * Get the event's poster.
  * 
  * @param int $event_id
+ * @return int|bool the id of the poster or false if the event was not found
  */
 function getEventPoster($event_id)
 {
@@ -872,7 +833,7 @@ function getEventPoster($event_id)
 	// Grab the results and return.
 	list ($poster) = $smcFunc['db_fetch_row']($request);
 	$smcFunc['db_free_result']($request);
-	return $poster;
+	return (int) $poster;
 }
 
 /**
@@ -926,9 +887,8 @@ function insertEvent(&$eventOptions)
 }
 
 /**
- * 
  * @param int $event_id
- * @param array $eventOptions
+ * @param array &$eventOptions
  */
 function modifyEvent($event_id, &$eventOptions)
 {
@@ -973,7 +933,7 @@ function modifyEvent($event_id, &$eventOptions)
 }
 
 /**
- * 
+ * Remove an event
  * @param int $event_id
  */
 function removeEvent($event_id)
@@ -994,8 +954,8 @@ function removeEvent($event_id)
 }
 
 /**
- * 
  * @param int $event_id
+ * @return array
  */
 function getEventProperties($event_id)
 {
@@ -1050,6 +1010,7 @@ function getEventProperties($event_id)
  * @param int $start
  * @param int $items_per_page
  * @param string $sort
+ * @return array
  */
 function list_getHolidays($start, $items_per_page, $sort)
 {
@@ -1073,7 +1034,7 @@ function list_getHolidays($start, $items_per_page, $sort)
 }
 
 /**
- * 
+ * @return int
  */
 function list_getNumHolidays()
 {
@@ -1088,12 +1049,11 @@ function list_getNumHolidays()
 	list($num_items) = $smcFunc['db_fetch_row']($request);
 	$smcFunc['db_free_result']($request);
 
-	return $num_items;
+	return (int) $num_items;
 }
 
 /**
- * 
- * @param array $holiday_ids
+ * @param array $holiday_ids An array of 
  */
 function removeHolidays($holiday_ids)
 {

Sources/Subs-MembersOnline.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Handle online users
+ * 
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,26 +16,11 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file currently only holds the function for showing a list of online
-	users used by the board index and SSI. In the future it'll also contain
-	functions used by the Who's online page.
-
-	array getMembersOnlineStats(array membersOnlineOptions)
-		- retrieve a list and several other statistics of the users currently
-		  online on the forum.
-		- used by the board index and SSI.
-		- also returns the membergroups of the users that are currently online.
-		- (optionally) hides members that chose to hide their online presense.
-*/
-
-// 
 /**
  * Retrieve a list and several other statistics of the users currently online.
- * - retrieve a list and several other statistics of the users currently
- *   online on the forum.
- * - used by the board index and SSI.
- * - also returns the membergroups of the users that are currently online.
- * - (optionally) hides members that chose to hide their online presense.
+ * Used by the board index and SSI.
+ * Also returns the membergroups of the users that are currently online.
+ * (optionally) hides members that chose to hide their online presense.
  * @param array $membersOnlineOptions
  * @return array
  */

Sources/Subs-Package.php

@@ -1,6 +1,11 @@
 <?php
 
 /**
+ * This file's central purpose of existence is that of making the package 
+ * manager work nicely.  It contains functions for handling tar.gz and zip
+ * files, as well as a simple xml parser to handle the xml package stuff.
+ * Not to mention a few functions to make file handling easier.
+ * 
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,24 +19,6 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file's central purpose of existence is that of making the package
-	manager work nicely.  It contains functions for handling tar.gz and zip
-	files, as well as a simple xml parser to handle the xml package stuff.
-	Not to mention a few functions to make file handling easier.
-
-	string package_crypt(
-
-
-	string fetch_web_data(
-
-
-	Creating your own package server:
-	---------------------------------------------------------------------------
-
-	Creating your own package:
-	---------------------------------------------------------------------------
-*/
-
 /**
  * Reads a .tar.gz file, filename, in and extracts file(s) from it.
  * essentially just a shortcut for read_tgz_data().

Sources/Subs-Post.php

@@ -550,7 +550,7 @@ function sendmail($to, $subject, $message, $from = null, $message_id = null, $se
 
 		// Call this function recursively for the hotmail addresses.
 		if (!empty($hotmail_to))
-			$mail_result = sendmail($hotmail_to, $subject, $message, $from, $message_id, $send_html, $priority, true);
+			$mail_result = sendmail($hotmail_to, $subject, $message, $from, $message_id, $send_html, $priority, true, $is_private);
 
 		// The remaining addresses no longer need the fix.
 		$hotmail_fix = false;

Sources/Subs-Recent.php

@@ -20,6 +20,7 @@ if (!defined('SMF'))
  * Get the latest posts of a forum.
  *
  * @param array $latestPostOptions
+ * @return array
  */
 function getLastPosts($latestPostOptions)
 {

Themes/default/css/index.css

@@ -1361,8 +1361,8 @@ ul#navigation li
 /* the content section */
 #content_section
 {
-	background: #FFFFFF url(../images/theme/frame_repeat.png) repeat-y top left;
-	padding-left: 20px;
+	background: #fff url(../images/theme/frame_repeat.png) repeat-y top left;
+	padding: 0 0 1px 20px;
 }
 #content_section div.frame
 {

Themes/default/index.template.php

@@ -35,7 +35,9 @@
 	http://www.simplemachines.org/
 */
 
-// Initialize the template... mainly little settings.
+/**
+ * Initialize the template... mainly little settings.
+ */
 function template_init()
 {
 	global $context, $settings, $options, $txt;
@@ -74,7 +76,9 @@ function template_init()
 	$settings['require_theme_strings'] = false;
 }
 
-// The main sub template above the content.
+/**
+ * The main sub template above the content.
+ */
 function template_html_above()
 {
 	global $context, $settings, $options, $scripturl, $txt, $modSettings;
@@ -99,6 +103,8 @@ function template_html_above()
 		echo '
 	<link rel="stylesheet" type="text/css" href="', $settings['theme_url'], '/css/rtl.css" />';
 
+	template_css();
+
 	// Here comes the JavaScript bits!
 	// Note that the Superfish function seems to like being called by the full syntax.
 	// It doesn't appear to like being called by short syntax. Please test if contemplating changes.
@@ -135,6 +141,8 @@ function template_html_above()
 		var ajax_notification_cancel_text = "', $txt['modify_cancel'], '";
 	// ]]></script>';
 
+	template_javascript();
+
 	echo '
 	<meta http-equiv="Content-Type" content="text/html; charset=', $context['character_set'], '" />
 	<meta name="description" content="', $context['page_title_html_safe'], '" />', !empty($context['meta_keywords']) ? '
@@ -378,11 +386,16 @@ function template_html_below()
 {
 	global $context, $settings, $options, $scripturl, $txt, $modSettings;
 
+	template_javascript(true);
+
 	echo '
 </body></html>';
 }
 
-// Show a linktree. This is that thing that shows "My Community | General Category | General Discussion"..
+/**
+ * Show a linktree. This is that thing that shows "My Community | General Category | General Discussion"..
+ * @param bool $force_show = false
+ */
 function theme_linktree($force_show = false)
 {
 	global $context, $settings, $options, $shown_linktree;
@@ -427,7 +440,9 @@ function theme_linktree($force_show = false)
 	$shown_linktree = true;
 }
 
-// Show the menu up top. Something like [home] [help] [profile] [logout]...
+/**
+ * Show the menu up top. Something like [home] [help] [profile] [logout]...
+ */
 function template_menu()
 {
 	global $context, $settings, $options, $scripturl, $txt;
@@ -488,8 +503,13 @@ function template_menu()
 		</div>';
 }
 
-// Generate a strip of buttons.
-function template_button_strip($button_strip, $direction = 'top', $strip_options = array())
+/**
+ * Generate a strip of buttons.
+ * @param array $button_strip
+ * @param string $direction = ''
+ * @param array $strip_options = array()
+ */
+function template_button_strip($button_strip, $direction = '', $strip_options = array())
 {
 	global $settings, $context, $txt, $scripturl;
 
@@ -524,4 +544,49 @@ function template_button_strip($button_strip, $direction = 'top', $strip_options
 		</div>';
 }
 
-?>
+/**
+ * Output the Javascript files
+ */
+function template_javascript($do_defered = false)
+{
+	global $context;
+
+	// Use this hook to minify/optimize Javascript files
+	call_integration_hook('pre_javascript_output');
+
+	foreach ($context['javascript_files'] as $filename => $options)
+		if ((!$do_defered && empty($options['defer'])) || ($do_defered && !empty($options['defer'])))
+			echo '
+		<script type="text/javascript" src="', $filename, '"></script>';
+}
+
+/**
+ * Output the Javascript vars
+ */
+function template_javascript_vars()
+{
+	global $context;
+
+	call_integration_hook('pre_javascript_vars_output');
+
+	foreach ($context['javascript_vars'] as $key => $value)
+		echo '
+		var ', $key, ' = ', $value;
+}
+
+/**
+ * Output the Javascript files
+ */
+function template_css()
+{
+	global $context;
+
+	// Use this hook to minify/optimize CSS files
+	call_integration_hook('pre_css_output');
+
+	foreach ($context['css_files'] as $filename => $options)
+		echo '
+		<script type="text/javascript" src="', $filename, '"></script>';
+}
+
+?>

subscriptions.php

@@ -1,6 +1,9 @@
 <?php
 
 /**
+ * This file is the file which all subscription gateways should call
+ * when a payment has been received - it sorts out the user status.
+ * 
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -11,14 +14,6 @@
  * @version 2.1 Alpha 1
  */
 
-/*
-	This file is the file which all subscription gateways should call
-	when a payment has been received - it sorts out the user status.
-
-	void generateSubscriptionError()
-	// log the error for posterity
-*/
-
 // Start things rolling by getting SMF alive...
 $ssi_guest_access = true;
 if (!file_exists(dirname(__FILE__) . '/SSI.php'))