! More doc cleanup, parts of 10630

Sources/ManageAttachments.php

@@ -434,11 +434,13 @@ function BrowseFiles()
 }
 
 /**
- * @todo this doesn't belong here.
- * @param $start
- * @param $items_per_page
- * @param $sort
- * @param $browse_type
+ * Returns the list of attachments files (avatars or not), recorded
+ * in the database, per the parameters received.
+ *
+ * @param int $start
+ * @param int $items_per_page
+ * @param string $sort
+ * @param string $browse_type, can be 'avatars' or ... not. :P
  */
 function list_getFiles($start, $items_per_page, $sort, $browse_type)
 {
@@ -494,8 +496,11 @@ function list_getFiles($start, $items_per_page, $sort, $browse_type)
 }
 
 /**
- * @todo refactor these model functions.
- * @param $browse_type
+ * Return the number of files of the specified type recorded in the database.
+ * (the specified type being attachments or avatars).
+ *
+ * @param string $browse_type, can be 'avatars' or not. (in which case they're
+ * attachments)
  */
 function list_getNumFiles($browse_type)
 {
@@ -679,12 +684,12 @@ function RemoveAttachmentByAge()
 
 	checkSession('post', 'admin');
 
-	// !!! Ignore messages in topics that are stickied?
+	// @todo Ignore messages in topics that are stickied?
 
 	// Deleting an attachment?
 	if ($_REQUEST['type'] != 'avatars')
 	{
-		// Get all the old attachments.
+		// Get rid of all the old attachments.
 		$messages = removeAttachments(array('attachment_type' => 0, 'poster_time' => (time() - 24 * 60 * 60 * $_POST['age'])), 'messages', true);
 
 		// Update the messages to reflect the change.
@@ -1534,7 +1539,10 @@ function ApproveAttach()
 
 	// Finally, we are there. Follow through!
 	if ($is_approve)
+	{
+		// Checked and deemed worthy.
 		ApproveAttachments($attachments);
+	}
 	else
 		removeAttachments(array('id_attach' => $attachments));
 

Sources/Profile-Modify.php

@@ -2535,7 +2535,9 @@ function profileSaveGroups(&$value)
 	return true;
 }
 
-// The avatar is incredibly complicated, what with the options... and what not.
+/**
+ * The avatar is incredibly complicated, what with the options... and what not.
+ */
 function profileSaveAvatarData(&$value)
 {
 	global $modSettings, $sourcedir, $smcFunc, $profile_vars, $cur_profile, $context;

Sources/Subs-Post.php

@@ -23,9 +23,6 @@ if (!defined('SMF'))
 		- cleans up links (javascript, etc.) and code/quote sections.
 		- won't convert \n's and a few other things if previewing is true.
 
-	string un_preparsecode(string message)
-		// !!!
-
 	void fixTags(string &message)
 		- used by preparsecode, fixes links in message and returns nothing.
 

Sources/Topic.php

@@ -0,0 +1,161 @@
+<?php
+
+/**
+ * This file takes care of actions on topics:
+ * locking and sticky-ing.
+ *
+ * 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' : ''));
+}
+
+?>