! Rename the controller for topic actions (lock / sticky) to Topic.php instead of LockTopic.php

! More and more code documentation spreading out. (several more files)

Sources/LockTopic.php

@@ -1,161 +0,0 @@
-<?php
-
-/**
- * This file only takes care of two things - locking and sticky-ing.
- * @todo and it's called after one of those. :P
- *
- * Simple Machines Forum (SMF)
- *
- * @package SMF
- * @author Simple Machines http://www.simplemachines.org
- * @copyright 2011 Simple Machines
- * @license http://www.simplemachines.org/about/smf/license.php BSD
- *
- * @version 2.0
- */
-
-if (!defined('SMF'))
-	die('Hacking attempt...');
-
-/**
- * Locks a topic... either by way of a moderator or the topic starter.
- * What this does:
- *  - locks a topic, toggles between locked/unlocked/admin locked.
- *  - only admins can unlock topics locked by other admins.
- *  - requires the lock_own or lock_any permission.
- *  - logs the action to the moderator log.
- *  - returns to the topic after it is done.
- *  - it is accessed via ?action=lock.
-*/
-function LockTopic()
-{
-	global $topic, $user_info, $sourcedir, $board, $smcFunc;
-
-	// Just quit if there's no topic to lock.
-	if (empty($topic))
-		fatal_lang_error('not_a_topic', false);
-
-	checkSession('get');
-
-	// Get Subs-Post.php for sendNotifications.
-	require_once($sourcedir . '/Subs-Post.php');
-
-	// Find out who started the topic - in case User Topic Locking is enabled.
-	$request = $smcFunc['db_query']('', '
-		SELECT id_member_started, locked
-		FROM {db_prefix}topics
-		WHERE id_topic = {int:current_topic}
-		LIMIT 1',
-		array(
-			'current_topic' => $topic,
-		)
-	);
-	list ($starter, $locked) = $smcFunc['db_fetch_row']($request);
-	$smcFunc['db_free_result']($request);
-
-	// Can you lock topics here, mister?
-	$user_lock = !allowedTo('lock_any');
-	if ($user_lock && $starter == $user_info['id'])
-		isAllowedTo('lock_own');
-	else
-		isAllowedTo('lock_any');
-
-	// Locking with high privileges.
-	if ($locked == '0' && !$user_lock)
-		$locked = '1';
-	// Locking with low privileges.
-	elseif ($locked == '0')
-		$locked = '2';
-	// Unlocking - make sure you don't unlock what you can't.
-	elseif ($locked == '2' || ($locked == '1' && !$user_lock))
-		$locked = '0';
-	// You cannot unlock this!
-	else
-		fatal_lang_error('locked_by_admin', 'user');
-
-	// Actually lock the topic in the database with the new value.
-	$smcFunc['db_query']('', '
-		UPDATE {db_prefix}topics
-		SET locked = {int:locked}
-		WHERE id_topic = {int:current_topic}',
-		array(
-			'current_topic' => $topic,
-			'locked' => $locked,
-		)
-	);
-
-	// If they are allowed a "moderator" permission, log it in the moderator log.
-	if (!$user_lock)
-		logAction($locked ? 'lock' : 'unlock', array('topic' => $topic, 'board' => $board));
-	// Notify people that this topic has been locked?
-	sendNotifications($topic, empty($locked) ? 'unlock' : 'lock');
-
-	// Back to the topic!
-	redirectexit('topic=' . $topic . '.' . $_REQUEST['start'] . (WIRELESS ? ';moderate' : ''));
-}
-
-/**
- * Sticky a topic.
- * Can't be done by topic starters - that would be annoying!
- * What this does:
- *  - stickies a topic - toggles between sticky and normal.
- *  - requires the make_sticky permission.
- *  - adds an entry to the moderator log.
- *  - when done, sends the user back to the topic.
- *  - accessed via ?action=sticky.
- */
-function Sticky()
-{
-	global $modSettings, $topic, $board, $sourcedir, $smcFunc;
-
-	// Make sure the user can sticky it, and they are stickying *something*.
-	isAllowedTo('make_sticky');
-
-	// You shouldn't be able to (un)sticky a topic if the setting is disabled.
-	if (empty($modSettings['enableStickyTopics']))
-		fatal_lang_error('cannot_make_sticky', false);
-
-	// You can't sticky a board or something!
-	if (empty($topic))
-		fatal_lang_error('not_a_topic', false);
-
-	checkSession('get');
-
-	// We need Subs-Post.php for the sendNotifications() function.
-	require_once($sourcedir . '/Subs-Post.php');
-
-	// Is this topic already stickied, or no?
-	$request = $smcFunc['db_query']('', '
-		SELECT is_sticky
-		FROM {db_prefix}topics
-		WHERE id_topic = {int:current_topic}
-		LIMIT 1',
-		array(
-			'current_topic' => $topic,
-		)
-	);
-	list ($is_sticky) = $smcFunc['db_fetch_row']($request);
-	$smcFunc['db_free_result']($request);
-
-	// Toggle the sticky value.... pretty simple ;).
-	$smcFunc['db_query']('', '
-		UPDATE {db_prefix}topics
-		SET is_sticky = {int:is_sticky}
-		WHERE id_topic = {int:current_topic}',
-		array(
-			'current_topic' => $topic,
-			'is_sticky' => empty($is_sticky) ? 1 : 0,
-		)
-	);
-
-	// Log this sticky action - always a moderator thing.
-	logAction(empty($is_sticky) ? 'sticky' : 'unsticky', array('topic' => $topic, 'board' => $board));
-	// Notify people that this topic has been stickied?
-	if (empty($is_sticky))
-		sendNotifications($topic, 'sticky');
-
-	// Take them back to the now stickied topic.
-	redirectexit('topic=' . $topic . '.' . $_REQUEST['start'] . (WIRELESS ? ';moderate' : ''));
-}
-
-?>

Sources/ManageMembers.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * Show a list of members or a selection of members.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,55 +16,15 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	Show a list of members or a selection of members.
-
-	void ViewMembers()
-		- the main entrance point for the Manage Members screen.
-		- called by ?action=admin;area=viewmembers.
-		- requires the moderate_forum permission.
-		- loads the ManageMembers template and ManageMembers language file.
-		- calls a function based on the given sub-action.
-
-	void ViewMemberlist()
-		- shows a list of members.
-		- called by ?action=admin;area=viewmembers;sa=all or ?action=admin;area=viewmembers;sa=query.
-		- requires the moderate_forum permission.
-		- uses the view_members sub template of the ManageMembers template.
-		- allows sorting on several columns.
-		- handles deletion of selected members.
-		- handles the search query sent by ?action=admin;area=viewmembers;sa=search.
-
-	void SearchMembers()
-		- search the member list, using one or more criteria.
-		- called by ?action=admin;area=viewmembers;sa=search.
-		- requires the moderate_forum permission.
-		- uses the search_members sub template of the ManageMembers template.
-		- form is submitted to action=admin;area=viewmembers;sa=query.
-
-	void MembersAwaitingActivation()
-		- show a list of members awaiting approval or activation.
-		- called by ?action=admin;area=viewmembers;sa=browse;type=approve or
-		  ?action=admin;area=viewmembers;sa=browse;type=activate.
-		- requires the moderate_forum permission.
-		- uses the admin_browse sub template of the ManageMembers template.
-		- allows instant approval or activation of (a selection of) members.
-		- list can be sorted on different columns.
-		- form submits to ?action=admin;area=viewmembers;sa=approve.
-
-	void AdminApprove()
-		- handles the approval, rejection, activation or deletion of members.
-		- called by ?action=admin;area=viewmembers;sa=approve.
-		- requires the moderate_forum permission.
-		- redirects to ?action=admin;area=viewmembers;sa=browse with the same parameters
-		  as the calling page.
-
-	int jeffsdatediff(int old)
-		- nifty function to calculate the number of days ago a given date was.
-		- requires a unix timestamp as input, returns an integer.
-		- in honour of Jeff Lewis, the original creator of...this function.
-		- the returned number of days is based on the forum time.
-*/
-
+/**
+ * The main entrance point for the Manage Members screen.
+ * As everyone else, it calls a function based on the given sub-action.
+ * Called by ?action=admin;area=viewmembers.
+ * Requires the moderate_forum permission.
+ *
+ * @uses ManageMembers template
+ * @uses ManageMembers language file.
+ */
 function ViewMembers()
 {
 	global $txt, $scripturl, $context, $modSettings, $smcFunc;
@@ -168,7 +130,15 @@ function ViewMembers()
 	$subActions[$_REQUEST['sa']][0]();
 }
 
-// View all members.
+/**
+ * View all members list. It allows sorting on several columns, and deletion of
+ * selected members. It also handles the search query sent by
+ * ?action=admin;area=viewmembers;sa=search.
+ * Called by ?action=admin;area=viewmembers;sa=all or ?action=admin;area=viewmembers;sa=query.
+ * Requires the moderate_forum permission.
+ *
+ * @uses the view_members sub template of the ManageMembers template.
+ */
 function ViewMemberlist()
 {
 	global $txt, $scripturl, $context, $modSettings, $sourcedir, $smcFunc, $user_info;
@@ -634,7 +604,14 @@ function ViewMemberlist()
 	$context['default_list'] = 'member_list';
 }
 
-// Search the member list, using one or more criteria.
+/**
+ * Search the member list, using one or more criteria.
+ * Called by ?action=admin;area=viewmembers;sa=search.
+ * Requires the moderate_forum permission.
+ * form is submitted to action=admin;area=viewmembers;sa=query.
+ *
+ * @uses the search_members sub template of the ManageMembers template.
+ */
 function SearchMembers()
 {
 	global $context, $txt, $smcFunc;
@@ -679,7 +656,16 @@ function SearchMembers()
 	$context['sub_template'] = 'search_members';
 }
 
-// List all members who are awaiting approval / activation
+/**
+ * List all members who are awaiting approval / activation, sortable on different columns.
+ * It allows instant approval or activation of (a selection of) members.
+ * Called by ?action=admin;area=viewmembers;sa=browse;type=approve
+ *  or ?action=admin;area=viewmembers;sa=browse;type=activate.
+ * The form submits to ?action=admin;area=viewmembers;sa=approve.
+ * Requires the moderate_forum permission.
+ *
+ * @uses the admin_browse sub template of the ManageMembers template.
+ */
 function MembersAwaitingActivation()
 {
 	global $txt, $context, $scripturl, $modSettings, $smcFunc;
@@ -1024,7 +1010,13 @@ function MembersAwaitingActivation()
 	createList($listOptions);
 }
 
-// Do the approve/activate/delete stuff
+/**
+ * This function handles the approval, rejection, activation or deletion of members.
+ * Called by ?action=admin;area=viewmembers;sa=approve.
+ * Requires the moderate_forum permission.
+ * Redirects to ?action=admin;area=viewmembers;sa=browse
+ * with the same parameters as the calling page.
+ */
 function AdminApprove()
 {
 	global $txt, $context, $scripturl, $modSettings, $sourcedir, $language, $user_info, $smcFunc;
@@ -1283,6 +1275,14 @@ function AdminApprove()
 	redirectexit('action=admin;area=viewmembers;sa=browse;type=' . $_REQUEST['type'] . ';sort=' . $_REQUEST['sort'] . ';filter=' . $current_filter . ';start=' . $_REQUEST['start']);
 }
 
+/**
+ * Nifty function to calculate the number of days ago a given date was.
+ * Requires a unix timestamp as input, returns an integer.
+ * Named in honour of Jeff Lewis, the original creator of...this function.
+ *
+ * @param $old
+ * @return int, the returned number of days, based on the forum time.
+ */
 function jeffsdatediff($old)
 {
 	// Get the current time as the user would see it...

Sources/ManageNews.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file manages... the news. :P
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,53 +16,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*
-	void ManageNews()
-		- the entrance point for all News and Newsletter screens.
-		- called by ?action=admin;area=news.
-		- does the permission checks.
-		- calls the appropriate function based on the requested sub-action.
-
-	void EditNews()
-		- changes the current news items for the forum.
-		- uses the ManageNews template and edit_news sub template.
-		- called by ?action=admin;area=news.
-		- requires the edit_news permission.
-		- writes an entry into the moderation log.
-		- uses the edit_news administration area.
-		- can be accessed with ?action=admin;sa=editnews.
-
-	void SelectMailingMembers()
-		- allows a user to select the membergroups to send their mailing to.
-		- uses the ManageNews template and email_members sub template.
-		- called by ?action=admin;area=news;sa=mailingmembers.
-		- requires the send_mail permission.
-		- form is submitted to ?action=admin;area=news;mailingcompose.
-
-	void ComposeMailing()
-		- shows a form to edit a forum mailing and its recipients.
-		- uses the ManageNews template and email_members_compose sub template.
-		- called by ?action=admin;area=news;sa=mailingcompose.
-		- requires the send_mail permission.
-		- form is submitted to ?action=admin;area=news;sa=mailingsend.
-
-	void SendMailing(bool clean_only = false)
-		- handles the sending of the forum mailing in batches.
-		- uses the ManageNews template and email_members_send sub template.
-		- called by ?action=admin;area=news;sa=mailingsend
-		- requires the send_mail permission.
-		- redirects to itself when more batches need to be sent.
-		- redirects to ?action=admin after everything has been sent.
-		- if clean_only is set will only clean the variables, put them in context, then return.
-
-	void NewsSettings()
-		- set general news and newsletter settings and permissions.
-		- uses the ManageNews template and news_settings sub template.
-		- called by ?action=admin;area=news;sa=settings.
-		- requires the forum_admin permission.
-*/
-
-// The controller; doesn't do anything, just delegates.
+/**
+ * The news dispatcher; doesn't do anything, just delegates.
+ * This is the entrance point for all News and Newsletter screens.
+ * Called by ?action=admin;area=news.
+ * It does the permission checks, and calls the appropriate function
+ * based on the requested sub-action.
+ */
 function ManageNews()
 {
 	global $context, $txt, $scripturl;
@@ -109,7 +71,17 @@ function ManageNews()
 	$subActions[$_REQUEST['sa']][0]();
 }
 
-// Let the administrator(s) edit the news.
+//
+/**
+ * Let the administrator(s) edit the news items for the forum.
+ * It writes an entry into the moderation log.
+ * This function uses the edit_news administration area.
+ * Called by ?action=admin;area=news.
+ * Requires the edit_news permission.
+ * Can be accessed with ?action=admin;sa=editnews.
+ *
+ * @uses ManageNews template, edit_news sub template.
+ */
 function EditNews()
 {
 	global $txt, $modSettings, $context, $sourcedir, $user_info;
@@ -170,6 +142,15 @@ function EditNews()
 	$context['page_title'] = $txt['admin_edit_news'];
 }
 
+/**
+ * This function allows a user to select the membergroups to send their
+ * mailing to.
+ * Called by ?action=admin;area=news;sa=mailingmembers.
+ * Requires the send_mail permission.
+ * Form is submitted to ?action=admin;area=news;mailingcompose.
+ *
+ * @uses the ManageNews template and email_members sub template.
+ */
 function SelectMailingMembers()
 {
 	global $txt, $context, $modSettings, $smcFunc;
@@ -286,7 +267,14 @@ function SelectMailingMembers()
 	$context['can_send_pm'] = allowedTo('pm_send');
 }
 
-// Email your members...
+/**
+ * Shows a form to edit a forum mailing and its recipients.
+ * Called by ?action=admin;area=news;sa=mailingcompose.
+ * Requires the send_mail permission.
+ * Form is submitted to ?action=admin;area=news;sa=mailingsend.
+ *
+ * @uses ManageNews template, email_members_compose sub-template.
+ */
 function ComposeMailing()
 {
 	global $txt, $sourcedir, $context, $smcFunc;
@@ -439,7 +427,16 @@ function ComposeMailing()
 	$context['default_message'] = htmlspecialchars($txt['message'] . "\n\n" . $txt['regards_team'] . "\n\n" . '{$board_url}');
 }
 
-// Send out the mailing!
+/**
+ * Handles the sending of the forum mailing in batches.
+ * Called by ?action=admin;area=news;sa=mailingsend
+ * Requires the send_mail permission.
+ * Redirects to itself when more batches need to be sent.
+ * Redirects to ?action=admin after everything has been sent.
+ *
+ * @param bool $clean_only = false; if set, it will only clean the variables, put them in context, then return.
+ * @uses the ManageNews template and email_members_send sub template.
+ */
 function SendMailing($clean_only = false)
 {
 	global $txt, $sourcedir, $context, $smcFunc;
@@ -766,6 +763,14 @@ function SendMailing($clean_only = false)
 	$context['sub_template'] = 'email_members_send';
 }
 
+/**
+ * Set general news and newsletter settings and permissions.
+ * Called by ?action=admin;area=news;sa=settings.
+ * Requires the forum_admin permission.
+ *
+ * @uses ManageNews template, news_settings sub-template.
+ * @param $return_config
+ */
 function ModifyNewsSettings($return_config = false)
 {
 	global $context, $sourcedir, $modSettings, $txt, $scripturl;

Sources/ManagePaid.php

@@ -1,6 +1,9 @@
 <?php
 
 /**
+ * This file contains all the administration functions for subscriptions.
+ * (and some more than that :P)
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,61 +17,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains all the screens that control settings for topics and
-	posts.
-
-	void ManagePaidSubscriptions()
-		- the main entrance point for the 'Paid Subscription' screen.
-		- accessed from ?action=admin;area=paidsubscribe.
-		- calls the right function based on the given sub-action.
-		- defaults to sub-action 'view'.
-		- requires admin_forum permission for admin based actions.
-
-	void ModifySubscriptionSettings()
-		- set any setting related to paid subscriptions.
-		- requires the moderate_forum permission
-		- accessed from ?action=admin;area=paidsubscribe;sa=settings.
-
-	void ViewSubscriptions()
-		- view a list of all the current subscriptions
-		- requires the admin_forum permission
-		- accessed from ?action=admin;area=paidsubscribe;sa=view.
-
-	void ModifySubscription()
-		- edit a subscription.
-		- accessed from ?action=admin;area=paidsubscribe;sa=modify.
-
-	void ViewSubscribedUsers()
-		- view a list of all the users who currently have a subscription.
-		- requires the admin_forum permission.
-		- subscription ID is required, in the form of $_GET['sid'].
-		- accessed from ?action=admin;area=paidsubscribe;sa=viewsub.
-
-	int list_getSubscribedUserCount()
-		// !!
-
-	array list_getSubscribedUsers()
-		// !!
-
-	void ModifyUserSubscription()
-		- edit a users subscription.
-		- accessed from ?action=admin;area=paidsubscribe;sa=modifyuser.
-
-	void reapplySubscriptions(array users)
-		- reapplies all subscription rules for each of the users.
-
-	void addSubscription(int id_subscribe, int id_member)
-		- add/extend a subscription for a member.
-
-	void removeSubscription(int id_subscribe, int id_member)
-		- remove a subscription from a user.
-
-	array loadPaymentGateways()
-		- checks the Sources directory for any files fitting the format of a payment gateway.
-		- loads each file to check it's valid.
-		- includes each file and returns the function name and whether it should work with this version of SMF.
-*/
-
+/**
+ * The main entrance point for the 'Paid Subscription' screen, calling
+ * the right function based on the given sub-action.
+ * It defaults to sub-action 'view'.
+ * Accessed from ?action=admin;area=paidsubscribe.
+ * It requires admin_forum permission for admin based actions.
+ */
 function ManagePaidSubscriptions()
 {
 	global $context, $txt, $scripturl, $sourcedir, $smcFunc, $modSettings;
@@ -112,7 +67,14 @@ function ManagePaidSubscriptions()
 	$subActions[$_REQUEST['sa']][0]();
 }
 
-// Modify which payment methods are to be used.
+/**
+ * Set any setting related to paid subscriptions, i.e.
+ * modify which payment methods are to be used.
+ * It requires the moderate_forum permission
+ * Accessed from ?action=admin;area=paidsubscribe;sa=settings.
+ *
+ * @param bool $return_config = false
+ */
 function ModifySubscriptionSettings($return_config = false)
 {
 	global $context, $txt, $modSettings, $sourcedir, $smcFunc, $scripturl;
@@ -219,7 +181,11 @@ function ModifySubscriptionSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
-// Are we looking at viewing the subscriptions?
+/**
+ * View a list of all the current subscriptions
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=paidsubscribe;sa=view.
+ */
 function ViewSubscriptions()
 {
 	global $context, $txt, $modSettings, $smcFunc, $sourcedir, $scripturl;
@@ -359,7 +325,10 @@ function ViewSubscriptions()
 	$context['default_list'] = 'subscription_list';
 }
 
-// Adding, editing and deleting subscriptions.
+/**
+ * Adding, editing and deleting subscriptions.
+ * Accessed from ?action=admin;area=paidsubscribe;sa=modify.
+ */
 function ModifySubscription()
 {
 	global $context, $txt, $modSettings, $smcFunc;
@@ -606,7 +575,13 @@ function ModifySubscription()
 	$smcFunc['db_free_result']($request);
 }
 
-// View all the users subscribed to a particular subscription!
+/**
+ * View all the users subscribed to a particular subscription.
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=paidsubscribe;sa=viewsub.
+ *
+ * Subscription ID is required, in the form of $_GET['sid'].
+ */
 function ViewSubscribedUsers()
 {
 	global $context, $txt, $modSettings, $scripturl, $options, $smcFunc, $sourcedir;
@@ -802,7 +777,14 @@ function ViewSubscribedUsers()
 	$context['default_list'] = 'subscribed_users_list';
 }
 
-// Returns how many people are subscribed to a paid subscription.
+/**
+ * Returns how many people are subscribed to a paid subscription.
+ * @todo refactor away
+ *
+ * @param int $id_sub
+ * @param string $search_string
+ * @param array $search_vars = array()
+ */
 function list_getSubscribedUserCount($id_sub, $search_string, $search_vars = array())
 {
 	global $smcFunc;
@@ -826,6 +808,17 @@ function list_getSubscribedUserCount($id_sub, $search_string, $search_vars = arr
 	return $memberCount;
 }
 
+/**
+ * Return the subscribed users list, for the given parameters.
+ * @todo refactor outta here
+ *
+ * @param int $start
+ * @param int $items_per_page
+ * @param string $sort
+ * @param int $id_sub
+ * @param string $search_string
+ * @param string $search_vars
+ */
 function list_getSubscribedUsers($start, $items_per_page, $sort, $id_sub, $search_string, $search_vars = array())
 {
 	global $smcFunc, $txt;
@@ -863,7 +856,10 @@ function list_getSubscribedUsers($start, $items_per_page, $sort, $id_sub, $searc
 	return $subscribers;
 }
 
-// Edit or add a user subscription.
+/**
+ * Edit or add a user subscription.
+ * Accessed from ?action=admin;area=paidsubscribe;sa=modifyuser.
+ */
 function ModifyUserSubscription()
 {
 	global $context, $txt, $modSettings, $smcFunc;
@@ -1193,7 +1189,11 @@ function ModifyUserSubscription()
 	}
 }
 
-// Re-apply subscription rules.
+/**
+ * Reapplies all subscription rules for each of the users.
+ *
+ * @param array $users
+ */
 function reapplySubscriptions($users)
 {
 	global $smcFunc;
@@ -1272,7 +1272,15 @@ function reapplySubscriptions($users)
 	}
 }
 
-// Add or extend a subscription of a user.
+/**
+ * Add or extend a subscription of a user.
+ *
+ * @param int $id_subscribe
+ * @param int $id_member
+ * @param string $renewal = 0, options 'D', 'W', 'M', 'Y'
+ * @param int $forceStartTime = 0
+ * @param int $forceEndTime = 0
+ */
 function addSubscription($id_subscribe, $id_member, $renewal = 0, $forceStartTime = 0, $forceEndTime = 0)
 {
 	global $context, $smcFunc;
@@ -1481,7 +1489,13 @@ function addSubscription($id_subscribe, $id_member, $renewal = 0, $forceStartTim
 	);
 }
 
-// Removes a subscription from a user, as in removes the groups.
+/**
+ * Removes a subscription from a user, as in removes the groups.
+ *
+ * @param $id_subscribe
+ * @param $id_member
+ * @param $delete
+ */
 function removeSubscription($id_subscribe, $id_member, $delete = false)
 {
 	global $context, $smcFunc;
@@ -1626,7 +1640,9 @@ function removeSubscription($id_subscribe, $id_member, $delete = false)
 		);
 }
 
-// This just kind of caches all the subscription data.
+/**
+ * This just kind of caches all the subscription data.
+ */
 function loadSubscriptions()
 {
 	global $context, $txt, $modSettings, $smcFunc;
@@ -1737,7 +1753,14 @@ function loadSubscriptions()
 	$smcFunc['db_free_result']($request);
 }
 
-// Load all the payment gateways.
+/**
+ * Load all the payment gateways.
+ * Checks the Sources directory for any files fitting the format of a payment gateway,
+ * loads each file to check it's valid, includes each file and returns the
+ * function name and whether it should work with this version of SMF.
+ *
+ * @return array
+ */
 function loadPaymentGateways()
 {
 	global $sourcedir;

Sources/ManagePermissions.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * ManagePermissions handles all possible permission stuff.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,77 +16,13 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	ManagePermissions handles all possible permission stuff. The following
-	functions are used:
-
-	void ModifyPermissions()
-		- calls the right function based on the given subaction.
-		- checks the permissions, based on the sub-action.
-		- called by ?action=managepermissions.
-		- loads the ManagePermissions language file.
-
-	void PermissionIndex()
-		- sets up the permissions by membergroup index page.
-		- called by ?action=managepermissions
-		- uses the permission_index template of the ManageBoards template.
-		- loads the ManagePermissions language and template.
-		- creates an array of all the groups with the number of members and permissions.
-
-	void SetQuickGroups()
-		- handles permission modification actions from the upper part of the
-		  permission manager index.
-		// !!!
-
-	void ModifyMembergroup()
-		// !!!
-
-	void ModifyMembergroup2()
-		// !!!
-
-	void GeneralPermissionSettings()
-		- a screen to set some general settings for permissions.
-
-	void setPermissionLevel(string level, int group, int profile = 'null')
-		- internal function to modify permissions to a pre-defined profile.
-		// !!!
-
-	void loadAllPermissions()
-		- internal function to load permissions into $context['permissions'].
-		// !!!
-
-	void loadPermissionProfiles()
-		// !!!
-
-	void EditPermissionProfiles()
-		// !!!
-
-	void init_inline_permissions(array permissions)
-		- internal function to initialise the inline permission settings.
-		- loads the ManagePermissions language and template.
-		- loads a context variables for each permission.
-		- used by several settings screens to set specific permissions.
-
-	void theme_inline_permissions(string permission)
-		- function called by templates to show a list of permissions settings.
-		- calls the template function template_inline_permissions().
-
-	save_inline_permissions(array permissions)
-		- general function to save the inline permissions sent by a form.
-		- does no session check.
-
-	void updateChildPermissions(array parent, int profile = null)
-		// !!!
-
-	void loadIllegalPermissions()
-		// !!!
-
-	void loadIllegalGuestPermissions()
-		- loads the permissions that can not be given to guests.
-		- stores the permissions in $context['non_guest_permissions'].
-
-	void ModifyPostModeration()
-		// !!!
-*/
+/**
+ * Dispaches to the right function based on the given subaction.
+ * Checks the permissions, based on the sub-action.
+ * Called by ?action=managepermissions.
+ *
+ * @uses ManagePermissions language file.
+ */
 
 function ModifyPermissions()
 {
@@ -136,6 +74,15 @@ function ModifyPermissions()
 	$subActions[$_REQUEST['sa']][0]();
 }
 
+/**
+ * Sets up the permissions by membergroup index page.
+ * Called by ?action=managepermissions
+ * Creates an array of all the groups with the number of members and permissions.
+ *
+ * @uses ManagePermissions language file.
+ * @uses ManagePermissions template file.
+ * @uses ManageBoards template, permission_index sub-template.
+ */
 function PermissionIndex()
 {
 	global $txt, $scripturl, $context, $settings, $modSettings, $smcFunc;
@@ -389,6 +336,9 @@ function PermissionIndex()
 	$context['sub_template'] = 'permission_index';
 }
 
+/**
+ * Handle permissions by board... more or less. :P
+ */
 function PermissionByBoard()
 {
 	global $context, $modSettings, $txt, $smcFunc, $sourcedir, $cat_tree, $boardList, $boards;
@@ -460,6 +410,10 @@ function PermissionByBoard()
 	$context['sub_template'] = 'by_board';
 }
 
+/**
+ * Handles permission modification actions from the upper part of the
+ * permission manager index.
+ */
 function SetQuickGroups()
 {
 	global $context, $smcFunc;
@@ -717,6 +671,9 @@ function SetQuickGroups()
 	redirectexit('action=admin;area=permissions;pid=' . $_REQUEST['pid']);
 }
 
+/**
+ * Initializes the necessary to modify a membergroup's permissions.
+ */
 function ModifyMembergroup()
 {
 	global $context, $txt, $modSettings, $smcFunc, $sourcedir;
@@ -865,6 +822,9 @@ function ModifyMembergroup()
 	$context['page_title'] = $txt['permissions_modify_group'];
 }
 
+/**
+ * This function actually saves modifications to a membergroup's board permissions.
+ */
 function ModifyMembergroup2()
 {
 	global $modSettings, $smcFunc, $context;
@@ -986,7 +946,11 @@ function ModifyMembergroup2()
 	redirectexit('action=admin;area=permissions;pid=' . $_GET['pid']);
 }
 
-// Screen for modifying general permission settings.
+/**
+ * A screen to set some general settings for permissions.
+ *
+ * @param bool $return_config = false
+ */
 function GeneralPermissionSettings($return_config = false)
 {
 	global $context, $modSettings, $sourcedir, $txt, $scripturl, $smcFunc;
@@ -1089,7 +1053,14 @@ function GeneralPermissionSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
-// Set the permission level for a specific profile, group, or group for a profile.
+/**
+ * Set the permission level for a specific profile, group, or group for a profile.
+ * @internal
+ *
+ * @param string $level
+ * @param int $group
+ * @param mixed $profile = null, int expected
+ */
 function setPermissionLevel($level, $group, $profile = 'null')
 {
 	global $smcFunc, $context;
@@ -1402,6 +1373,12 @@ function setPermissionLevel($level, $group, $profile = 'null')
 		fatal_lang_error('no_access', false);
 }
 
+/**
+ * Load permissions into $context['permissions'].
+ * @internal
+ *
+ * @param string $loadType, options: 'classic' or 'simple'
+ */
 function loadAllPermissions($loadType = 'classic')
 {
 	global $context, $txt, $modSettings;
@@ -1696,7 +1673,19 @@ function loadAllPermissions($loadType = 'classic')
 		}
 }
 
-// Initialize a form with inline permissions.
+//
+/**
+ * Initialize a form with inline permissions settings.
+ * It loads a context variables for each permission.
+ * This function is used by several settings screens to set specific permissions.
+ * @internal
+ *
+ * @param array $permissions
+ * @param array $excluded_groups = array()
+ *
+ * @uses ManagePermissions language
+ * @uses ManagePermissions template.
+ */
 function init_inline_permissions($permissions, $excluded_groups = array())
 {
 	global $context, $txt, $modSettings, $smcFunc;
@@ -1784,7 +1773,13 @@ function init_inline_permissions($permissions, $excluded_groups = array())
 	}
 }
 
-// Show a collapsible box to set a specific permission.
+/**
+ * Show a collapsible box to set a specific permission.
+ * The function is called by templates to show a list of permissions settings.
+ * Calls the template function template_inline_permissions().
+ *
+ * @param string $permission
+ */
 function theme_inline_permissions($permission)
 {
 	global $context;
@@ -1795,7 +1790,12 @@ function theme_inline_permissions($permission)
 	template_inline_permissions();
 }
 
-// Save the permissions of a form containing inline permissions.
+/**
+ * Save the permissions of a form containing inline permissions.
+ * @internal
+ *
+ * @param array $permissions
+ */
 function save_inline_permissions($permissions)
 {
 	global $context, $smcFunc;
@@ -1850,6 +1850,9 @@ function save_inline_permissions($permissions)
 	updateSettings(array('settings_updated' => time()));
 }
 
+/**
+ * Load permissions profiles.
+ */
 function loadPermissionProfiles()
 {
 	global $context, $txt, $smcFunc;
@@ -1880,7 +1883,9 @@ function loadPermissionProfiles()
 	$smcFunc['db_free_result']($request);
 }
 
-// Add/Edit/Delete profiles.
+/**
+ * Add/Edit/Delete profiles.
+ */
 function EditPermissionProfiles()
 {
 	global $context, $txt, $smcFunc;
@@ -2027,7 +2032,12 @@ function EditPermissionProfiles()
 	}
 }
 
-// This function updates the permissions of any groups based off this group.
+/**
+ * This function updates the permissions of any groups based off this group.
+ *
+ * @param mixed $parents (array or int)
+ * @param mixed $profile = null, int expected
+ */
 function updateChildPermissions($parents, $profile = null)
 {
 	global $smcFunc;
@@ -2147,7 +2157,9 @@ function updateChildPermissions($parents, $profile = null)
 	}
 }
 
-// Load permissions someone cannot grant.
+/**
+ * Load permissions someone cannot grant.
+ */
 function loadIllegalPermissions()
 {
 	global $context;
@@ -2161,7 +2173,10 @@ function loadIllegalPermissions()
 		$context['illegal_permissions'][] = 'manage_permissions';
 }
 
-// Load all the permissions that can not be given to guests.
+/**
+ * Loads the permissions that can not be given to guests.
+ * Stores the permissions in $context['non_guest_permissions'].
+*/
 function loadIllegalGuestPermissions()
 {
 	global $context;
@@ -2200,7 +2215,9 @@ function loadIllegalGuestPermissions()
 	);
 }
 
-// Present a nice way of applying post moderation.
+/**
+ * Present a nice way of applying post moderation.
+ */
 function ModifyPostModeration()
 {
 	global $context, $txt, $smcFunc, $modSettings;

Sources/ManagePosts.php

@@ -1,6 +1,8 @@
 <?php
 
 /**
+ * This file contains all the screens that control settings for topics and posts.
+ *
  * Simple Machines Forum (SMF)
  *
  * @package SMF
@@ -14,45 +16,14 @@
 if (!defined('SMF'))
 	die('Hacking attempt...');
 
-/*	This file contains all the screens that control settings for topics and
-	posts.
-
-	void ManagePostSettings()
-		- the main entrance point for the 'Posts and topics' screen.
-		- accessed from ?action=admin;area=postsettings.
-		- calls the right function based on the given sub-action.
-		- defaults to sub-action 'posts'.
-		- requires (and checks for) the admin_forum permission.
-
-	void SetCensor()
-		- shows an interface to set and test word censoring.
-		- requires the admin_forum permission.
-		- uses the Admin template and the edit_censored sub template.
-		- tests the censored word if one was posted.
-		- uses the censor_vulgar, censor_proper, censorWholeWord, and
-		  censorIgnoreCase settings.
-		- accessed from ?action=admin;area=postsettings;sa=censor.
-
-	void ModifyPostSettings()
-		- set any setting related to posts and posting.
-		- requires the admin_forum permission
-		- uses the edit_post_settings sub template of the Admin template.
-		- accessed from ?action=admin;area=postsettings;sa=posts.
-
-	void ModifyBBCSettings()
-		- set a few Bulletin Board Code settings.
-		- requires the admin_forum permission
-		- uses the edit_bbc_settings sub template of the Admin template.
-		- accessed from ?action=admin;area=postsettings;sa=bbc.
-		- loads a list of Bulletin Board Code tags to allow disabling tags.
-
-	void ModifyTopicSettings()
-		- set any setting related to topics.
-		- requires the admin_forum permission
-		- uses the edit_topic_settings sub template of the Admin template.
-		- accessed from ?action=admin;area=postsettings;sa=topics.
-*/
-
+/**
+ * The main entrance point for the 'Posts and topics' screen.
+ * Like all others, it checks permissions, then forwards to the right function
+ * based on the given sub-action.
+ * Defaults to sub-action 'posts'.
+ * Accessed from ?action=admin;area=postsettings.
+ * Requires (and checks for) the admin_forum permission.
+ */
 function ManagePostSettings()
 {
 	global $context, $txt, $scripturl;
@@ -97,7 +68,15 @@ function ManagePostSettings()
 	$subActions[$_REQUEST['sa']]();
 }
 
-// Set the censored words.
+/**
+ * Shows an interface to set and test censored words.
+ * It uses the censor_vulgar, censor_proper, censorWholeWord, and censorIgnoreCase
+ * settings.
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=postsettings;sa=censor.
+ *
+ * @uses the Admin template and the edit_censored sub template.
+ */
 function SetCensor()
 {
 	global $txt, $modSettings, $context, $smcFunc;
@@ -176,7 +155,14 @@ function SetCensor()
 	$context['page_title'] = $txt['admin_censored_words'];
 }
 
-// Modify all settings related to posts and posting.
+/**
+ * Modify any setting related to posts and posting.
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=postsettings;sa=posts.
+ *
+ * @param $return_config
+ * @uses Admin template, edit_post_settings sub-template.
+ */
 function ModifyPostSettings($return_config = false)
 {
 	global $context, $txt, $modSettings, $scripturl, $sourcedir, $smcFunc, $db_prefix;
@@ -263,7 +249,14 @@ function ModifyPostSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
-// Bulletin Board Code...a lot of Bulletin Board Code.
+/**
+ * Set a few Bulletin Board Code settings. It loads a list of Bulletin Board Code tags to allow disabling tags.
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=postsettings;sa=bbc.
+ *
+ * @param bool $return_config = false
+ * @uses Admin template, edit_bbc_settings sub-template.
+ */
 function ModifyBBCSettings($return_config = false)
 {
 	global $context, $txt, $modSettings, $helptxt, $scripturl, $sourcedir;
@@ -315,7 +308,14 @@ function ModifyBBCSettings($return_config = false)
 	prepareDBSettingContext($config_vars);
 }
 
-// Function for modifying topic settings. Not very exciting.
+/**
+ * Modify any setting related to topics.
+ * Requires the admin_forum permission.
+ * Accessed from ?action=admin;area=postsettings;sa=topics.
+
+ * @param $return_config
+ * @uses Admin template, edit_topic_settings sub-template.
+ */
 function ModifyTopicSettings($return_config = false)
 {
 	global $context, $txt, $modSettings, $sourcedir, $scripturl;

index.php

@@ -271,7 +271,7 @@ function smf_main()
 		'jseditor' => array('Subs-Editor.php', 'EditorMain'),
 		'jsmodify' => array('Post.php', 'JavaScriptModify'),
 		'jsoption' => array('Themes.php', 'SetJavaScript'),
-		'lock' => array('LockTopic.php', 'LockTopic'),
+		'lock' => array('Topic.php', 'LockTopic'),
 		'lockvoting' => array('Poll.php', 'LockVoting'),
 		'login' => array('LogInOut.php', 'Login'),
 		'login2' => array('LogInOut.php', 'Login2'),
@@ -312,7 +312,7 @@ function smf_main()
 		'spellcheck' => array('Subs-Post.php', 'SpellCheck'),
 		'splittopics' => array('SplitTopics.php', 'SplitTopics'),
 		'stats' => array('Stats.php', 'DisplayStats'),
-		'sticky' => array('LockTopic.php', 'Sticky'),
+		'sticky' => array('Topic.php', 'Sticky'),
 		'theme' => array('Themes.php', 'ThemesMain'),
 		'trackip' => array('Profile-View.php', 'trackIP'),
 		'about:mozilla' => array('Karma.php', 'BookOfUnknown'),