Skip to content

/SMF2.1

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

! Doc cleanup/fixes (part 1 of ?) 

Signed-off-by: Michael Eshom <oldiesmann@oldiesmann.us>
  • Loading branch information...
commit 636f34befeff1bac9902ca02425691eb47aed404 1 parent d0cf844
@Oldiesmann Oldiesmann authored
Unified Split
Showing with 711 additions and 354 deletions.
  1. +219 −33 SSI.php
  2. +5 −4 Sources/Admin.php
  3. +5 −4 Sources/Calendar.php
  4. +15 −18 Sources/Class-BrowserDetect.php
  5. +21 −18 Sources/Class-CurlFetchWeb.php
  6. +3 −1 Sources/Class-Graphics.php
  7. +48 −51 Sources/Class-Package.php
  8. +35 −32 Sources/Class-SearchAPI.php
  9. +14 −16 Sources/Class-TOTP.php
  10. +3 −2 Sources/Display.php
  11. +1 −1  Sources/Drafts.php
  12. +2 −2 Sources/Errors.php
  13. +3 −3 Sources/Groups.php
  14. +6 −0 Sources/Help.php
  15. +7 −3 Sources/Likes.php
  16. +9 −9 Sources/Load.php
  17. +12 −12 Sources/LogInOut.php
  18. +9 −8 Sources/Logging.php
  19. +23 −14 Sources/ManageAttachments.php
  20. +76 −61 Sources/ManageBans.php
  21. +2 −2 Sources/ManageBoards.php
  22. +2 −1  Sources/ManageCalendar.php
  23. +8 −4 Sources/ManageLanguages.php
  24. +11 −9 Sources/ManageMail.php
  25. +8 −11 Sources/ManageMaintenance.php
  26. +2 −2 Sources/ManageMembers.php
  27. +4 −3 Sources/ManageNews.php
  28. +23 −20 Sources/ManagePaid.php
  29. +6 −0 Sources/tasks/ApprovePost-Notify.php
  30. +6 −0 Sources/tasks/ApproveReply-Notify.php
  31. +6 −0 Sources/tasks/Buddy-Notify.php
  32. +6 −0 Sources/tasks/CreatePost-Notify.php
  33. +6 −0 Sources/tasks/EventNew-Notify.php
  34. +6 −0 Sources/tasks/GroupReq-Notify.php
  35. +6 −0 Sources/tasks/Likes-Notify.php
  36. +6 −0 Sources/tasks/MemberReport-Notify.php
  37. +6 −0 Sources/tasks/MemberReportReply-Notify.php
  38. +6 −0 Sources/tasks/MsgReport-Notify.php
  39. +6 −0 Sources/tasks/MsgReportReply-Notify.php
  40. +6 −0 Sources/tasks/Register-Notify.php
  41. +35 −2 cron.php
  42. +1 −0  index.php
  43. +25 −7 proxy.php
  44. +2 −1  subscriptions.php
View
252 SSI.php
@@ -198,14 +198,21 @@
return true;
-// This shuts down the SSI and shows the footer.
+/**
+ * This shuts down the SSI and shows the footer.
+ * @return void
+ */
function ssi_shutdown()
{
if (!isset($_GET['ssi_function']) || $_GET['ssi_function'] != 'shutdown')
template_footer();
}
-// Display a welcome message, like: Hey, User, you have 0 messages, 0 are new.
+/**
+ * Display a welcome message, like: Hey, User, you have 0 messages, 0 are new.
+ * @param string $output_method The output method. If 'echo', will display everything. Otherwise returns an array of user info.
+ * @return void|array Displays a welcome message or returns an array of user data depending on output_method.
+ */
function ssi_welcome($output_method = 'echo')
{
global $context, $txt, $scripturl;
@@ -222,7 +229,11 @@ function ssi_welcome($output_method = 'echo')
return $context['user'];
}
-// Display a menu bar, like is displayed at the top of the forum.
+/**
+ * Display a menu bar, like is displayed at the top of the forum.
+ * @param string $output_method The output method. If 'echo', will display the menu, otherwise returns an array of menu data.
+ * @return void|array Displays the menu or returns an array of menu data depending on output_method.
+ */
function ssi_menubar($output_method = 'echo')
{
global $context;
@@ -234,7 +245,12 @@ function ssi_menubar($output_method = 'echo')
return $context['menu_buttons'];
}
-// Show a logout link.
+/**
+ * Show a logout link.
+ * @param string $redirect_to A URL to redirect the user to after they log out.
+ * @param string $output_method The output method. If 'echo', shows a logout link, otherwise returns the HTML for it.
+ * @return void|string Displays a logout link or returns its HTML depending on output_method.
+ */
function ssi_logout($redirect_to = '', $output_method = 'echo')
{
global $context, $txt, $scripturl;
@@ -254,7 +270,15 @@ function ssi_logout($redirect_to = '', $output_method = 'echo')
return $link;
}
-// Recent post list: [board] Subject by Poster Date
+/**
+ * Recent post list: [board] Subject by Poster Date
+ * @param int $num_recent How many recent posts to display
+ * @param null|array $exclude_boards If set, doesn't show posts from the specified boards
+ * @param null|array $include_boards If set, only includes posts from the specified boards
+ * @param string $output_method The output method. If 'echo', displays the posts, otherwise returns an array of information about them.
+ * @param bool $limit_body Whether or not to only show the first 384 characters of each post
+ * @return void|array Displays a list of recent posts or returns an array of information about them depending on output_method.
+ */
function ssi_recentPosts($num_recent = 8, $exclude_boards = null, $include_boards = null, $output_method = 'echo', $limit_body = true)
{
global $modSettings, $context;
@@ -296,7 +320,13 @@ function ssi_recentPosts($num_recent = 8, $exclude_boards = null, $include_board
return ssi_queryPosts($query_where, $query_where_params, $num_recent, 'm.id_msg DESC', $output_method, $limit_body);
}
-// Fetch a post with a particular ID. By default will only show if you have permission to the see the board in question - this can be overridden.
+/**
+ * Fetches one or more posts by ID.
+ * @param array $post_ids An array containing the IDs of the posts to show
+ * @param bool $override_permissions Whether to ignore permissions. If true, will show posts even if the user doesn't have permission to see them.
+ * @param string $output_method The output method. If 'echo', displays the posts, otherwise returns an array of info about them
+ * @return void|array Displays the specified posts or returns an array of info about them, depending on output_method.
+ */
function ssi_fetchPosts($post_ids = array(), $override_permissions = false, $output_method = 'echo')
{
global $modSettings;
@@ -321,7 +351,17 @@ function ssi_fetchPosts($post_ids = array(), $override_permissions = false, $out
return ssi_queryPosts($query_where, $query_where_params, '', 'm.id_msg DESC', $output_method, false, $override_permissions);
}
-// This removes code duplication in other queries - don't call it direct unless you really know what you're up to.
+/**
+ * This handles actually pulling post info. Called from other functions to eliminate duplication.
+ * @param string $query_where The WHERE clause for the query
+ * @param array $query_where_params An array of parameters for the WHERE clause
+ * @param int $query_limit The maximum number of rows to return
+ * @param string $query_order The ORDER BY clause for the query
+ * @param string $output_method The output method. If 'echo', displays the posts, otherwise returns an array of info about them.
+ * @param bool $limit_body If true, will only show the first 384 characters of the post rather than all of it
+ * @param bool|false $override_permissions Whether or not to ignore permissions. If true, will show all posts regardless of whether the user can actually see them
+ * @return void|array Displays the posts or returns an array of info about them, depending on output_method
+ */
function ssi_queryPosts($query_where = '', $query_where_params = array(), $query_limit = 10, $query_order = 'm.id_msg DESC', $output_method = 'echo', $limit_body = false, $override_permissions = false)
{
global $scripturl, $txt, $user_info;
@@ -428,7 +468,14 @@ function ssi_queryPosts($query_where = '', $query_where_params = array(), $query
</table>';
}
-// Recent topic list: [board] Subject by Poster Date
+/**
+ * Recent topic list: [board] Subject by Poster Date
+ * @param int $num_recent How many recent topics to show
+ * @param null|array $exclude_boards If set, exclude topics from the specified board(s)
+ * @param null|array $include_boards If set, only include topics from the specified board(s)
+ * @param string $output_method The output method. If 'echo', displays a list of topics, otherwise returns an array of info about them
+ * @return void|array Either displays a list of topics or returns an array of info about them, depending on output_method.
+ */
function ssi_recentTopics($num_recent = 8, $exclude_boards = null, $include_boards = null, $output_method = 'echo')
{
global $settings, $scripturl, $txt, $user_info;
@@ -583,7 +630,12 @@ function ssi_recentTopics($num_recent = 8, $exclude_boards = null, $include_boar
</table>';
}
-// Show the top poster's name and profile link.
+/**
+ * Shows a list of top posters
+ * @param int $topNumber How many top posters to list
+ * @param string $output_method The output method. If 'echo', will display a list of users, otherwise returns an array of info about them.
+ * @return void|array Either displays a list of users or returns an array of info about them, depending on output_method.
+ */
function ssi_topPoster($topNumber = 1, $output_method = 'echo')
{
global $scripturl, $smcFunc;
@@ -620,7 +672,12 @@ function ssi_topPoster($topNumber = 1, $output_method = 'echo')
echo implode(', ', $temp_array);
}
-// Show boards by activity.
+/**
+ * Shows a list of top boards based on activity
+ * @param int $num_top How many boards to display
+ * @param string $output_method The output method. If 'echo', displays a list of boards, otherwise returns an array of info about them.
+ * @return void|array Displays a list of the top boards or returns an array of info about them, depending on output_method.
+ */
function ssi_topBoards($num_top = 10, $output_method = 'echo')
{
global $txt, $scripturl, $user_info, $modSettings, $smcFunc;
@@ -677,6 +734,13 @@ function ssi_topBoards($num_top = 10, $output_method = 'echo')
}
// Shows the top topics.
+/**
+ * Shows a list of top topics based on views or replies
+ * @param string $type Can be either replies or views
+ * @param int $num_topics How many topics to display
+ * @param string $output_method The output method. If 'echo', displays a list of topics, otherwise returns an array of info about them.
+ * @return void|array Either displays a list of topics or returns an array of info about them, depending on output_method.
+ */
function ssi_topTopics($type = 'replies', $num_topics = 10, $output_method = 'echo')
{
global $txt, $scripturl, $modSettings, $smcFunc;
@@ -761,19 +825,33 @@ function ssi_topTopics($type = 'replies', $num_topics = 10, $output_method = 'ec
</table>';
}
-// Shows the top topics, by replies.
+/**
+ * Top topics based on replies
+ * @param int $num_topics How many topics to show
+ * @param string $output_method The output method. If 'echo', displays a list of topics, otherwise returns an array of info about them
+ * @return void|array Either displays a list of top topics or returns an array of info about them, depending on output_method.
+ */
function ssi_topTopicsReplies($num_topics = 10, $output_method = 'echo')
{
return ssi_topTopics('replies', $num_topics, $output_method);
}
-// Shows the top topics, by views.
+/**
+ * Top topics based on views
+ * @param int $num_topics How many topics to show
+ * @param string $output_method The output method. If 'echo', displays a list of topics, otherwise returns an array of info about them
+ * @return void|array Either displays a list of top topics or returns an array of info about them, depending on output_method.
+ */
function ssi_topTopicsViews($num_topics = 10, $output_method = 'echo')
{
return ssi_topTopics('views', $num_topics, $output_method);
}
-// Show a link to the latest member: Please welcome, Someone, out latest member.
+/**
+ * Show a link to the latest member: Please welcome, Someone, our latest member.
+ * @param string $output_method The output method. If 'echo', returns a string with a link to the latest member's profile, otherwise returns an array of info about them.
+ * @return void|array Displays a "welcome" message for the latest member or returns an array of info about them, depending on output_method.
+ */
function ssi_latestMember($output_method = 'echo')
{
global $txt, $context;
@@ -785,7 +863,12 @@ function ssi_latestMember($output_method = 'echo')
return $context['common_stats']['latest_member'];
}
-// Fetch a random member - if type set to 'day' will only change once a day!
+/**
+ * Fetches a random member.
+ * @param string $random_type If 'day', only fetches a new random member once a day.
+ * @param string $output_method The output method. If 'echo', displays a link to the member's profile, otherwise returns an array of info about them.
+ * @return void|array Displays a link to a random member's profile or returns an array of info about them depending on output_method.
+ */
function ssi_randomMember($random_type = '', $output_method = 'echo')
{
global $modSettings;
@@ -833,7 +916,12 @@ function ssi_randomMember($random_type = '', $output_method = 'echo')
return $result;
}
-// Fetch a specific member.
+/**
+ * Fetch specific members
+ * @param array $member_ids The IDs of the members to fetch
+ * @param string $output_method The output method. If 'echo', displays a list of links to the members' profiles, otherwise returns an array of info about them.
+ * @return void|array Displays links to the specified members' profiles or returns an array of info about them, depending on output_method.
+ */
function ssi_fetchMember($member_ids = array(), $output_method = 'echo')
{
if (empty($member_ids))
@@ -854,7 +942,12 @@ function ssi_fetchMember($member_ids = array(), $output_method = 'echo')
return ssi_queryMembers($query_where, $query_where_params, '', 'id_member', $output_method);
}
-// Get all members of a group.
+/**
+ * Get al members in the specified group
+ * @param int $group_id The ID of the group to get members from
+ * @param string $output_method The output method. If 'echo', returns a list of group members, otherwise returns an array of info about them.
+ * @return void|array Displays a list of group members or returns an array of info about them, depending on output_method.
+ */
function ssi_fetchGroupMembers($group_id = null, $output_method = 'echo')
{
if ($group_id === null)
@@ -872,7 +965,15 @@ function ssi_fetchGroupMembers($group_id = null, $output_method = 'echo')
return ssi_queryMembers($query_where, $query_where_params, '', 'real_name', $output_method);
}
-// Fetch some member data!
+/**
+ * Pulls info about members based on the specified parameters. Used by other functions to eliminate duplication.
+ * @param string $query_where The info for the WHERE clause of the query
+ * @param array $query_where_params The parameters for the WHERE clause
+ * @param string|int $query_limit The number of rows to return or an empty string to return all
+ * @param string $query_order The info for the ORDER BY clause of the query
+ * @param string $output_method The output method. If 'echo', displays a list of members, otherwise returns an array of info about them
+ * @return void|array Displays a list of members or returns an array of info about them, depending on output_method.
+ */
function ssi_queryMembers($query_where = null, $query_where_params = array(), $query_limit = '', $query_order = 'id_member DESC', $output_method = 'echo')
{
global $smcFunc, $memberContext;
@@ -937,7 +1038,11 @@ function ssi_queryMembers($query_where = null, $query_where_params = array(), $q
return $query_members;
}
-// Show some basic stats: Total This: XXXX, etc.
+/**
+ * Show some basic stats: Total This: XXXX, etc.
+ * @param string $output_method The output method. If 'echo', displays the stats, otherwise returns an array of info about them
+ * @return void|array Doesn't return anything if the user can't view stats. Otherwise either displays the stats or returns an array of info about them, depending on output_method.
+ */
function ssi_boardStats($output_method = 'echo')
{
global $txt, $scripturl, $modSettings, $smcFunc;
@@ -980,7 +1085,11 @@ function ssi_boardStats($output_method = 'echo')
', $txt['total_boards'], ': ', comma_format($totals['boards']);
}
-// Shows a list of online users: YY Guests, ZZ Users and then a list...
+/**
+ * Shows a list of online users: YY Guests, ZZ Users and then a list...
+ * @param string $output_method The output method. If 'echo', displays a list, otherwise returns an array of info about the online users.
+ * @return void|array Either displays a list of online users or returns an array of info about them, depending on output_method.
+ */
function ssi_whosOnline($output_method = 'echo')
{
global $user_info, $txt, $sourcedir, $settings;
@@ -1025,7 +1134,11 @@ function ssi_whosOnline($output_method = 'echo')
[' . implode(']&nbsp;&nbsp;[', $return['membergroups']) . ']';
}
-// Just like whosOnline except it also logs the online presence.
+/**
+ * Just like whosOnline except it also logs the online presence.
+ * @param string $output_method The output method. If 'echo', displays a list, otherwise returns an array of info about the online users.
+ * @return void|array Either displays a list of online users or returns an aray of info about them, depending on output_method.
+ */
function ssi_logOnline($output_method = 'echo')
{
writeLog();
@@ -1037,6 +1150,12 @@ function ssi_logOnline($output_method = 'echo')
}
// Shows a login box.
+/**
+ * Shows a login box
+ * @param string $redirect_to The URL to redirect the user to after they login
+ * @param string $output_method The output method. If 'echo' and the user is a guest, displays a login box, otherwise returns whether the user is a guest
+ * @return void|bool Either displays a login box or returns whether the user is a guest, depending on whether the user is logged in and output_method.
+ */
function ssi_login($redirect_to = '', $output_method = 'echo')
{
global $scripturl, $txt, $user_info, $context, $modSettings;
@@ -1073,7 +1192,11 @@ function ssi_login($redirect_to = '', $output_method = 'echo')
}
-// Show the most-voted-in poll.
+/**
+ * Show the top poll based on votes
+ * @param string $output_method The output method. If 'echo', displays the poll, otherwise returns an array of info about it
+ * @return void|array Either shows the top poll or returns an array of info about it, depending on output_method.
+ */
function ssi_topPoll($output_method = 'echo')
{
// Just use recentPoll, no need to duplicate code...
@@ -1081,6 +1204,12 @@ function ssi_topPoll($output_method = 'echo')
}
// Show the most recently posted poll.
+/**
+ * Shows the most recent poll
+ * @param bool $topPollInstead Whether to show the top poll (based on votes) instead of the most recent one
+ * @param string $output_method The output method. If 'echo', displays the poll, otherwise returns an array of info about it.
+ * @return void|array Either shows the poll or returns an array of info about it, depending on output_method.
+ */
function ssi_recentPoll($topPollInstead = false, $output_method = 'echo')
{
global $txt, $boardurl, $user_info, $context, $smcFunc, $modSettings;
@@ -1211,6 +1340,12 @@ function ssi_recentPoll($topPollInstead = false, $output_method = 'echo')
echo $txt['poll_cannot_see'];
}
+/**
+ * Shows the poll from the specified topic
+ * @param null|int $topic The topic to show the poll from. If null, $_REQUEST['ssi_topic'] will be used instead.
+ * @param string $output_method The output method. If 'echo', displays the poll, otherwise returns an array of info about it.
+ * @return void|array Either displays the poll or returns an array of info about it, depending on output_method.
+ */
function ssi_showPoll($topic = null, $output_method = 'echo')
{
global $txt, $boardurl, $user_info, $context, $smcFunc, $modSettings;
@@ -1384,7 +1519,9 @@ function ssi_showPoll($topic = null, $output_method = 'echo')
echo $txt['poll_cannot_see'];
}
-// Takes care of voting - don't worry, this is done automatically.
+/**
+ * Handles voting in a poll (done automatically)
+ */
function ssi_pollVote()
{
global $context, $db_prefix, $user_info, $sc, $smcFunc, $sourcedir, $modSettings;
@@ -1493,6 +1630,11 @@ function ssi_pollVote()
}
// Show a search box.
+/**
+ * Shows a search box
+ * @param string $output_method The output method. If 'echo', displays a search box, otherwise returns the URL of the search page.
+ * @return void|string Displays a search box or returns the URL to the search page depending on output_method. If you don't have permission to search, the function won't return anything.
+ */
function ssi_quickSearch($output_method = 'echo')
{
global $scripturl, $txt, $context;
@@ -1509,7 +1651,11 @@ function ssi_quickSearch($output_method = 'echo')
</form>';
}
-// Show what would be the forum news.
+/**
+ * Show a random forum news item
+ * @param string $output_method The output method. If 'echo', shows the news item, otherwise returns it.
+ * @return void|string Shows or returns a random forum news item, depending on output_method.
+ */
function ssi_news($output_method = 'echo')
{
global $context;
@@ -1522,7 +1668,11 @@ function ssi_news($output_method = 'echo')
echo $context['random_news_line'];
}
-// Show today's birthdays.
+/**
+ * Show today's birthdays.
+ * @param string $output_method The output method. If 'echo', displays a list of users, otherwise returns an array of info about them.
+ * @return void|array Displays a list of users or returns an array of info about them depending on output_method.
+ */
function ssi_todaysBirthdays($output_method = 'echo')
{
global $scripturl, $modSettings, $user_info;
@@ -1544,7 +1694,11 @@ function ssi_todaysBirthdays($output_method = 'echo')
<a href="', $scripturl, '?action=profile;u=', $member['id'], '"><span class="fix_rtl_names">' . $member['name'] . '</span>' . (isset($member['age']) ? ' (' . $member['age'] . ')' : '') . '</a>' . (!$member['is_last'] ? ', ' : '');
}
-// Show today's holidays.
+/**
+ * Shows today's holidays.
+ * @param string $output_method The output method. If 'echo', displays a list of holidays, otherwise returns an array of info about them.
+ * @return void|array Displays a list of holidays or returns an array of info about them depending on output_method
+ */
function ssi_todaysHolidays($output_method = 'echo')
{
global $modSettings, $user_info;
@@ -1565,7 +1719,10 @@ function ssi_todaysHolidays($output_method = 'echo')
', implode(', ', $return['calendar_holidays']);
}
-// Show today's events.
+/**
+ * @param string $output_method The output method. If 'echo', displays a list of events, otherwise returns an array of info about them.
+ * @return void|array Displays a list of events or returns an array of info about them depending on output_method
+ */
function ssi_todaysEvents($output_method = 'echo')
{
global $modSettings, $user_info;
@@ -1592,7 +1749,11 @@ function ssi_todaysEvents($output_method = 'echo')
}
}
-// Show all calendar entires for today. (birthdays, holidays, and events.)
+/**
+ * Shows today's calendar items (events, birthdays and holidays)
+ * @param string $output_method The output method. If 'echo', displays a list of calendar items, otherwise returns an array of info about them.
+ * @return void|array Displays a list of calendar items or returns an array of info about them depending on output_method
+ */
function ssi_todaysCalendar($output_method = 'echo')
{
global $modSettings, $txt, $scripturl, $user_info;
@@ -1639,7 +1800,15 @@ function ssi_todaysCalendar($output_method = 'echo')
}
}
-// Show the latest news, with a template... by board.
+/**
+ * Show the latest news, with a template... by board.
+ * @param null|int $board The ID of the board to get the info from. Defaults to $board or $_GET['board'] if not set.
+ * @param null|int $limit How many items to show. Defaults to $_GET['limit'] or 5 if not set.
+ * @param null|int $start Start with the specified item. Defaults to $_GET['start'] or 0 if not set.
+ * @param null|int $length How many characters to show from each post. Defaults to $_GET['length'] or 0 (no limit) if not set.
+ * @param string $output_method The output method. If 'echo', displays the news items, otherwise returns an array of info about them.
+ * @return void|array Displays the news items or returns an array of info about them, depending on output_method.
+ */
function ssi_boardNews($board = null, $limit = null, $start = null, $length = null, $output_method = 'echo')
{
global $scripturl, $txt, $settings, $modSettings, $context;
@@ -1871,7 +2040,12 @@ function ssi_boardNews($board = null, $limit = null, $start = null, $length = nu
}
}
-// Show the most recent events.
+/**
+ * Show the most recent events
+ * @param int $max_events The maximum number of events to show
+ * @param string $output_method The output method. If 'echo', displays the events, otherwise returns an array of info about them.
+ * @return void|array Displays the events or returns an array of info about them, depending on output_method.
+ */
function ssi_recentEvents($max_events = 7, $output_method = 'echo')
{
global $user_info, $scripturl, $modSettings, $txt, $context, $smcFunc;
@@ -1955,7 +2129,13 @@ function ssi_recentEvents($max_events = 7, $output_method = 'echo')
}
}
-// Check the passed id_member/password. If $is_username is true, treats $id as a username.
+/**
+ * Checks whether the specified password is correct for the specified user.
+ * @param int|string $id The ID or username of a user
+ * @param string $password The password to check
+ * @param bool $is_username If true, treats $id as a username rather than a user ID
+ * @return bool Whether or not the password is correct.
+ */
function ssi_checkPassword($id = null, $password = null, $is_username = false)
{
global $smcFunc;
@@ -1979,8 +2159,14 @@ function ssi_checkPassword($id = null, $password = null, $is_username = false)
return hash_verify_password($user, $password, $pass) && $active == 1;
}
-// We want to show the recent attachments outside of the forum.
-function ssi_recentAttachments($num_attachments = 10, $attachment_ext = array(), $output_method = 'echo')
+/**
+ * Shows the most recent attachments that the user can see
+ * @param int $num_attachments How many to show
+ * @param array $attachment_ext Only shows attachments with the specified extensions ('jpg', 'gif', etc.) if set
+ * @param string $output_method The output method. If 'echo', displays a table with links/info, otherwise returns an array with information about the attachments
+ * @return void|array Displays a table of attachment info or returns an array containing info about the attachments, depending on output_method.
+ */
+function ssi_recentAttachmenets($num_attachments = 10, $attachment_ext = array(), $output_method = 'echo')
{
global $smcFunc, $modSettings, $scripturl, $txt, $settings;
@@ -2095,4 +2281,4 @@ function ssi_recentAttachments($num_attachments = 10, $attachment_ext = array(),
</table>';
}
-?>
+?>
View
9 Sources/Admin.php
@@ -17,9 +17,9 @@
die('No direct access...');
/**
- * The main admin handling function.
- * It initialises all the basic context required for the admin center.
- * It passes execution onto the relevant admin section.
+ * The main admin handling function.<br>
+ * It initialises all the basic context required for the admin center.<br>
+ * It passes execution onto the relevant admin section.<br>
* If the passed section is not found it shows the admin home page.
*/
function AdminMain()
@@ -40,7 +40,7 @@ function AdminMain()
// Some preferences.
$context['admin_preferences'] = !empty($options['admin_preferences']) ? unserialize($options['admin_preferences']) : array();
- // Define all the menu structure - see Subs-Menu.php for details!
+ /** @var array $admin_areas Defines the menu structure for the admin center. See {@link Subs-Menu.php Subs-Menu.php} for details! */
$admin_areas = array(
'forum' => array(
'title' => $txt['admin_main'],
@@ -811,6 +811,7 @@ function AdminSearchInternal()
/**
* All this does is pass through to manage members.
+ * {@see ViewMembers()}
*/
function AdminSearchMember()
{
View
9 Sources/Calendar.php
@@ -26,6 +26,7 @@
* It uses the main sub template in the Calendar template.
* It goes to the month and year passed in 'month' and 'year' by get or post.
* It is accessed through ?action=calendar.
+ * @return void
*/
function CalendarMain()
{
@@ -369,10 +370,10 @@ function CalendarPost()
/**
* This function offers up a download of an event in iCal 2.0 format.
*
- * follows the conventions in RFC5546 http://tools.ietf.org/html/rfc5546
- * sets events as all day events since we don't have hourly events
- * will honor and set multi day events
- * sets a sequence number if the event has been modified
+ * Follows the conventions in {@link http://tools.ietf.org/html/rfc5546 RFC5546}
+ * Sets events as all day events since we don't have hourly events
+ * Will honor and set multi day events
+ * Sets a sequence number if the event has been modified
*
* @todo .... allow for week or month export files as well?
*/
View
33 Sources/Class-BrowserDetect.php
@@ -15,6 +15,7 @@
die('No direct access...');
/**
+ * Class browser_detector
* This class is an experiment for the job of correctly detecting browsers and settings needed for them.
* - Detects the following browsers
* - Opera, Webkit, Firefox, Web_tv, Konqueror, IE, Gecko
@@ -28,16 +29,12 @@
class browser_detector
{
/**
- * Holds all browsers information. Its contents will be placed into $context['browser'].
- *
- * @var array
+ * @var array Holds all the browser information. Its contents will be placed into $context['browser']
*/
private $_browsers = null;
/**
- * Holds if the detected device may be a mobile one
- *
- * @var boolean
+ * @var boolean Whether or not this might be a mobile device
*/
private $_is_mobile = null;
@@ -101,7 +98,7 @@ function detectBrowser()
/**
* Determine if the browser is Opera or not
- * @return boolean true if the browser is Opera otherwise false
+ * @return boolean Whether or not this is Opera
*/
function isOpera()
{
@@ -112,7 +109,7 @@ function isOpera()
/**
* Determine if the browser is IE or not
- * @return boolean true if the browser is IE otherwise false
+ * @return boolean true Whether or not the browser is IE
*/
function isIe()
{
@@ -124,7 +121,7 @@ function isIe()
/**
* Determine if the browser is IE11 or not
- * @return boolean true if the browser is IE11 otherwise false
+ * @return boolean Whether or not the browser is IE11
*/
function isIe11()
{
@@ -137,7 +134,7 @@ function isIe11()
/**
* Determine if the browser is a Webkit based one or not
- * @return boolean true if the browser is Webkit based otherwise false
+ * @return boolean Whether or not this is a Webkit-based browser
*/
function isWebkit()
{
@@ -148,7 +145,7 @@ function isWebkit()
/**
* Determine if the browser is Firefox or one of its variants
- * @return boolean true if the browser is Firefox otherwise false
+ * @return boolean Whether or not this is Firefox (or one of its variants)
*/
function isFirefox()
{
@@ -159,7 +156,7 @@ function isFirefox()
/**
* Determine if the browser is WebTv or not
- * @return boolean true if the browser is WebTv otherwise false
+ * @return boolean Whether or not this is WebTV
*/
function isWebTv()
{
@@ -170,7 +167,7 @@ function isWebTv()
/**
* Determine if the browser is konqueror or not
- * @return boolean true if the browser is konqueror otherwise false
+ * @return boolean Whether or not this is Konqueror
*/
function isKonqueror()
{
@@ -181,7 +178,7 @@ function isKonqueror()
/**
* Determine if the browser is Gecko or not
- * @return boolean true if the browser is Gecko otherwise false
+ * @return boolean Whether or not this is a Gecko-based browser
*/
function isGecko()
{
@@ -191,8 +188,8 @@ function isGecko()
}
/**
- * Determine if the browser is OperaMini or not
- * @return boolean true if the browser is OperaMini otherwise false
+ * Determine if the browser is Opera Mini or not
+ * @return boolean Whether or not this is Opera Mini
*/
function isOperaMini()
{
@@ -204,8 +201,8 @@ function isOperaMini()
}
/**
- * Determine if the browser is OperaMobi or not
- * @return boolean true if the browser is OperaMobi otherwise false
+ * Determine if the browser is Opera Mobile or not
+ * @return boolean Whether or not this is Opera Mobile
*/
function isOperaMobi()
{
View
39 Sources/Class-CurlFetchWeb.php
@@ -14,6 +14,7 @@
die('No direct access...');
/**
+ * Class curl_fetch_web_data
* Simple cURL class to fetch a web page
* Properly redirects even with safe mode and basedir restrictions
* Can provide simple post options to a page
@@ -41,7 +42,7 @@ class curl_fetch_web_data
/**
* Set the default items for this class
*
- * @var array
+ * @var array $default_options
*/
private $default_options = array(
CURLOPT_RETURNTRANSFER => 1, // Get returned value as a string (don't output it)
@@ -61,8 +62,9 @@ class curl_fetch_web_data
* Start the curl object
* - allow for user override values
*
- * @param array $options cURL options as an array
- * @param int $max_redirect use to override the default of 3
+ * @param array $options An array of cURL options
+ * @param int $max_redirect Maximum number of redirects
+ * @return void
*/
public function __construct($options = array(), $max_redirect = 3)
{
@@ -80,6 +82,7 @@ public function __construct($options = array(), $max_redirect = 3)
*
* @param string $url the site we are going to fetch
* @param array $post_data any post data as form name => value
+ * @return object An instance of the curl_fetch_web_data class
*/
public function get_url_data($url, $post_data = array())
{
@@ -101,9 +104,9 @@ public function get_url_data($url, $post_data = array())
* - stores responses (url, code, error, headers, body) in the response array
* - detects 301, 302, 307 codes and will redirect to the given response header location
*
- * @param string $url site to fetch
- * @param boolean $redirect flag to indicate if this was a redirect request or not
- * @return boolean
+ * @param string $url The site to fetch
+ * @param bool $redirect Whether or not this was a redirect request
+ * @return void|bool Sets various properties of the class or returns false if the URL isn't specified
*/
private function curl_request($url, $redirect = false)
{
@@ -158,9 +161,9 @@ private function curl_request($url, $redirect = false)
/**
* Used if being redirected to ensure we have a fully qualified address
*
- * @param string $last_url where we went to
- * @param string $new_url where we were redirected to
- * @return string new url location
+ * @param string $last_url The URL we went to
+ * @param string $new_url The URL we were redirected to
+ * @return string The new URL that was in the HTTP header
*/
private function get_redirect_url($last_url = '', $new_url = '')
{
@@ -183,8 +186,8 @@ private function get_redirect_url($last_url = '', $new_url = '')
* - called as ->result() will return the full final array
* - called as ->result('body') to just return the page source of the result
*
- * @param string $area used to return an area such as body, header, error
- * @return string
+ * @param string $area Used to return an area such as body, header, error
+ * @return string The response
*/
public function result($area = '')
{
@@ -202,7 +205,7 @@ public function result($area = '')
* - Can be called as ->result_raw(x) where x is a specific loop results.
* - Call as ->result_raw() for everything.
*
- * @param string $response_number
+ * @param string $response_number Which response we want to get
* @return array|string The entire response array or just the specified response
*/
public function result_raw($response_number = '')
@@ -221,7 +224,7 @@ public function result_raw($response_number = '')
* - forms the date (for post) in to a string var=xyz&var2=abc&var3=123
* - drops vars with @ since we don't support sending files (uploading)
*
- * @param array|string $post_data
+ * @param array|string $post_data The raw POST data
* @return string A string of post data
*/
private function build_post_data($post_data)
@@ -245,7 +248,7 @@ private function build_post_data($post_data)
* Sets the final cURL options for the current call
* - overwrites our default values with user supplied ones or appends new user ones to what we have
* - sets the callback function now that $this is existing
- *
+ * @return void
*/
private function set_options()
{
@@ -274,8 +277,8 @@ private function set_options()
* Called to initiate a redirect from a 301, 302 or 307 header
* - resets the cURL options for the loop, sets the referrer flag
*
- * @param string $target_url
- * @param string $referer_url
+ * @param string $target_url The URL we want to redirect to
+ * @param string $referer_url The URL that we're redirecting from
*/
private function redirect($target_url, $referer_url)
{
@@ -289,8 +292,8 @@ private function redirect($target_url, $referer_url)
* Callback function to parse returned headers
* - lowercases everything to make it consistent
*
- * @param type $cr
- * @param string $header
+ * @param type $cr Not sure what this is used for?
+ * @param string $header The header
* @return int The length of the header
*/
private function header_callback($cr, $header)
View
4 Sources/Class-Graphics.php
@@ -23,6 +23,8 @@
die('No direct access...');
/**
+ * Class gif_lzw_compression
+ *
* An implementation of the LZW compression algorithm
*/
class gif_lzw_compression
@@ -30,7 +32,7 @@ class gif_lzw_compression
public $MAX_LZW_BITS;
public $Fresh, $CodeSize, $SetCodeSize, $MaxCode, $MaxCodeSize, $FirstCode, $OldCode;
public $ClearCode, $EndCode, $Next, $Vals, $Stack, $sp, $Buf, $CurBit, $LastBit, $Done, $LastByte;
-
+
public function __construct()
{
$this->MAX_LZW_BITS = 12;
View
99 Sources/Class-Package.php
@@ -17,25 +17,24 @@
die('No direct access...');
/**
- * Class representing an xml array. Reads in xml, allows you to access it simply. Version 1.1.
+ * Class xmlArray
+ * Represents an XML array
*/
class xmlArray
{
/**
- * holds xml parsed results
- * @var array
+ * @var array Holds parsed XML results
*/
public $array;
/**
- * holds debugging level
- * @var int
+ * @var int The debugging level
*/
public $debug_level;
/**
* holds trim level textual data
- * @var bool
+ * @var bool Holds trim level textual data
*/
public $trim;
@@ -44,9 +43,9 @@ class xmlArray
* Example use:
* $xml = new xmlArray(file('data.xml'));
*
- * @param string $data the xml data or an array of, unless is_clone is true.
- * @param bool $auto_trim default false, used to automatically trim textual data.
- * @param int $level default null, the debug level, specifies whether notices should be generated for missing elements and attributes.
+ * @param string $data The xml data or an array of, unless is_clone is true.
+ * @param bool $auto_trim Used to automatically trim textual data.
+ * @param int $level The debug level. Specifies whether notices should be generated for missing elements and attributes.
* @param bool $is_clone default false. If is_clone is true, the xmlArray is cloned from another - used internally only.
*/
public function __construct($data, $auto_trim = false, $level = null, $is_clone = false)
@@ -93,8 +92,8 @@ public function name()
* unless get_elements is true.
* Example use:
* $data = $xml->fetch('html/head/title');
- * @param string $path - the path to the element to fetch
- * @param bool $get_elements - whether to include elements
+ * @param string $path The path to the element to fetch
+ * @param bool $get_elements Whether to include elements
* @return string The value or attribute of the specified element
*/
public function fetch($path, $get_elements = false)
@@ -132,8 +131,8 @@ public function fetch($path, $get_elements = false)
* or return_set is true.
* Example use:
* $element = $xml->path('html/body');
- * @param $path string - the path to the element to get
- * @param $return_full bool - always return full result set
+ * @param $path string The path to the element to get
+ * @param $return_full bool Whether to return the full result set
* @return xmlArray, a new xmlArray.
*/
public function path($path, $return_full = false)
@@ -196,8 +195,8 @@ public function path($path, $return_full = false)
* Example use,
* echo $xml->exists('html/body') ? 'y' : 'n';
*
- * @param string $path - the path to the element to get.
- * @return boolean
+ * @param string $path The path to the element to get.
+ * @return boolean Whether the specified path exists
*/
public function exists($path)
{
@@ -233,8 +232,8 @@ public function exists($path)
* Count the number of occurrences of a path.
* Example use:
* echo $xml->count('html/head/meta');
- * @param string $path - the path to search for.
- * @return int, the number of elements the path matches.
+ * @param string $path The path to search for.
+ * @return int The number of elements the path matches.
*/
public function count($path)
{
@@ -258,8 +257,8 @@ public function count($path)
* of elements, an array of xmlArray's is returned for use with foreach.
* Example use:
* foreach ($xml->set('html/body/p') as $p)
- * @param $path string - the path to search for.
- * @return array, an array of xmlArray objects
+ * @param $path string The path to search for.
+ * @return array An array of xmlArray objects
*/
public function set($path)
{
@@ -287,8 +286,8 @@ public function set($path)
* Create an xml file from an xmlArray, the specified path if any.
* Example use:
* echo $this->create_xml();
- * @param string $path - the path to the element. (optional)
- * @return string, xml-formatted string.
+ * @param string $path The path to the element. (optional)
+ * @return string Xml-formatted string.
*/
public function create_xml($path = null)
{
@@ -316,7 +315,7 @@ public function create_xml($path = null)
* Example use:
* print_r($xml->to_array());
*
- * @param string $path the path to output.
+ * @param string $path The path to output.
* @return array An array of XML data
*/
public function to_array($path = null)
@@ -342,7 +341,7 @@ public function to_array($path = null)
/**
* Parse data into an array. (privately used...)
*
- * @param string $data to parse
+ * @param string $data The data to parse
* @return array The parsed array
*/
protected function _parse($data)
@@ -493,6 +492,7 @@ protected function _parse($data)
*
* @param array $array An array of element data
* @param null|int $indent How many levels to indent the elements (null = no indent)
+ * @return string The formatted XML
*/
protected function _xml($array, $indent)
{
@@ -520,7 +520,7 @@ protected function _xml($array, $indent)
$inside_elements = false;
$output_el = '';
- // Run through and recurively output all the elements or attrbutes inside this.
+ // Run through and recursively output all the elements or attrbutes inside this.
foreach ($array as $k => $v)
{
if (substr($k, 0, 1) == '@')
@@ -544,8 +544,8 @@ protected function _xml($array, $indent)
/**
* Return an element as an array
*
- * @param array $array
- * @return string|array A string with the element's value or an array of element datas
+ * @param array $array An array of data
+ * @return string|array A string with the element's value or an array of element data
*/
protected function _array($array)
{
@@ -609,7 +609,7 @@ function _to_cdata($data)
/**
* Turn the CDATAs back to normal text.
*
- * @param string $data
+ * @param string $data The data with CDATA tags
* @return string The transformed data
*/
protected function _from_cdata($data)
@@ -629,7 +629,7 @@ protected function _from_cdata($data)
/**
* Given an array, return the text from that array. (recursive and privately used.)
*
- * @param array $array
+ * @param array $array An aray of data
* @return string The text from the array
*/
protected function _fetch($array)
@@ -660,10 +660,10 @@ protected function _fetch($array)
/**
* Get a specific array by path, one level down. (privately used...)
*
- * @param array $array
- * @param string $path
- * @param int $level
- * @param bool $no_error
+ * @param array $array An array of data
+ * @param string $path The path
+ * @param int $level How far deep into the array we should go
+ * @param bool $no_error Whether or not to ignore errors
* @return string|array The specified array (or the contents of said array if there's only one result)
*/
protected function _path($array, $path, $level, $no_error = false)
@@ -722,43 +722,40 @@ protected function _path($array, $path, $level, $no_error = false)
}
/**
+ * Class ftp_connection
* Simple FTP protocol implementation.
*
- * http://www.faqs.org/rfcs/rfc959.html
+ * @see http://www.faqs.org/rfcs/rfc959.html
*/
class ftp_connection
{
/**
- * holds the connection response
- * @var type
+ * @var string Holds the connection response
*/
public $connection;
/**
- * holds any errors
- * @var string
+ * @var string Holds any errors
*/
public $error;
/**
- * holds last message from the server
- * @var string
+ * @var string Holds the last message from the server
*/
public $last_message;
/**
- * Passive connection
- * @var boolean
+ * @var boolean Whether or not this is a passive connection
*/
public $pasv;
/**
* Create a new FTP connection...
*
- * @param string $ftp_server
- * @param int $ftp_port
- * @param string $ftp_user
- * @param string $ftp_pass
+ * @param string $ftp_server The server to connect to
+ * @param int $ftp_port The port to connect to
+ * @param string $ftp_user The username
+ * @param string $ftp_pass The password
*/
public function __construct($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = 'ftpclient@simplemachines.org')
{
@@ -774,10 +771,10 @@ public function __construct($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous'
/**
* Connects to a server
*
- * @param string $ftp_server
- * @param int $ftp_port
- * @param string $ftp_user
- * @param string $ftp_pass
+ * @param string $ftp_server The address of the server
+ * @param int $ftp_port The port
+ * @param string $ftp_user The username
+ * @param string $ftp_pass The password
*/
public function connect($ftp_server, $ftp_port = 21, $ftp_user = 'anonymous', $ftp_pass = 'ftpclient@simplemachines.org')
{
@@ -1002,7 +999,7 @@ public function create_file($ftp_file)
* Generates a direcotry listing for the current directory
*
* @param string $ftp_path The path to the directory
- * @param type $search Whether or not to get a recursive directory listing
+ * @param bool $search Whether or not to get a recursive directory listing
* @return string|boolean The results of the command or false if unsuccessful
*/
public function list_dir($ftp_path = '', $search = false)
@@ -1048,7 +1045,7 @@ public function list_dir($ftp_path = '', $search = false)
*
* @param string $file The name of a file
* @param string $listing A directory listing or null to generate one
- * @return string|boolean
+ * @return string|boolean The name of the file or false if it wasn't found
*/
public function locate($file, $listing = null)
{
View
67 Sources/Class-SearchAPI.php
@@ -11,6 +11,9 @@
* @version 2.1 Beta 2
*/
+/**
+ * Interface search_api_interface
+ */
interface search_api_interface
{
/**
@@ -19,9 +22,9 @@
* they need not be declared
*
* @access public
- * @param string $methodName
- * @param array $query_params
- * @return boolean
+ * @param string $methodName The method
+ * @param array $query_params Any parameters for the query
+ * @return boolean Whether or not the specified method is supported
*/
public function supportsMethod($methodName, $query_params = array());
@@ -29,7 +32,7 @@ public function supportsMethod($methodName, $query_params = array());
* Whether this method is valid for implementation or not
*
* @access public
- * @return bool
+ * @return bool Whether or not this method is valid
*/
public function isValid();
@@ -41,7 +44,7 @@ public function isValid();
* @access public
* @param string $a Word A
* @param string $b Word B
- * @return int
+ * @return int An integer indicating how the words should be sorted
*/
public function searchSort($a, $b);
@@ -49,10 +52,10 @@ public function searchSort($a, $b);
* Callback while preparing indexes for searching
*
* @access public
- * @param string $word
- * @param array $wordsSearch
- * @param array $wordsExclude
- * @param bool $isExcluded
+ * @param string $word A word to index
+ * @param array $wordsSearch Search words
+ * @param array $wordsExclude Words to exclude
+ * @param bool $isExcluded Whether the specfied word should be excluded
*/
public function prepareIndexes($word, array &$wordsSearch, array &$wordsExclude, $isExcluded);
@@ -60,32 +63,32 @@ public function prepareIndexes($word, array &$wordsSearch, array &$wordsExclude,
* Search for indexed words.
*
* @access public
- * @param array $words
- * @param array $search_data
+ * @param array $words An array of words
+ * @param array $search_data An array of search data
* @return mixed
*/
public function indexedWordQuery(array $words, array $search_data);
/**
* Callback when a post is created
- * {@see createPost()}
+ * @see createPost()
*
* @access public
- * @param array $msgOptions
- * @param array $topicOptions
- * @param array $posterOptions
+ * @param array $msgOptions An array of post data
+ * @param array $topicOptions An array of topic data
+ * @param array $posterOptions An array of info about the person who made this post
* @return void
*/
public function postCreated(array &$msgOptions, array &$topicOptions, array &$posterOptions);
/**
* Callback when a post is modified
- * {@see modifyPost()}
+ * @see modifyPost()
*
* @access public
- * @param array $msgOptions
- * @param array $topicOptions
- * @param array $posterOptions
+ * @param array $msgOptions An array of post data
+ * @param array $topicOptions An array of topic data
+ * @param array $posterOptions An array of info about the person who made this post
* @return void
*/
public function postModified(array &$msgOptions, array &$topicOptions, array &$posterOptions);
@@ -94,7 +97,7 @@ public function postModified(array &$msgOptions, array &$topicOptions, array &$p
* Callback when a post is removed
*
* @access public
- * @param int $id_msg
+ * @param int $id_msg The ID of the post that was removed
* @return void
*/
public function postRemoved($id_msg);
@@ -103,7 +106,7 @@ public function postRemoved($id_msg);
* Callback when a topic is removed
*
* @access public
- * @param array $topics
+ * @param array $topics The ID(s) of the removed topic(s)
* @return void
*/
public function topicsRemoved(array $topics);
@@ -112,8 +115,8 @@ public function topicsRemoved(array $topics);
* Callback when a topic is moved
*
* @access public
- * @param array $topics
- * @param int $board_to
+ * @param array $topics The ID(s) of the moved topic(s)
+ * @param int $board_to The board that the topics were moved to
* @return void
*/
public function topicsMoved(array $topics, $board_to);
@@ -122,9 +125,9 @@ public function topicsMoved(array $topics, $board_to);
* Callback for actually performing the search query
*
* @access public
- * @param array $query_params
- * @param array $searchWords
- * @param array $excludedIndexWords
+ * @param array $query_params An array of parameters for the query
+ * @param array $searchWords The words that were searched for
+ * @param array $excludedIndexWords Indexed words that should be excluded
* @param array $participants
* @param array $searchArray
* @return mixed
@@ -132,23 +135,23 @@ public function topicsMoved(array $topics, $board_to);
public function searchQuery(array $query_params, array $searchWords, array $excludedIndexWords, array $participants, array $searchArray);
}
+/**
+ * Class search_api
+ */
abstract class search_api implements search_api_interface
{
/**
- * This is the last version of SMF that this was tested on, to protect against API changes.
- * @var type
+ * @var string The last version of SMF that this was tested on. Helps protect against API changes.
*/
public $version_compatible = 'SMF 2.1 Beta 2';
/**
- * This won't work with versions of SMF less than this.
- * @var type
+ * @var string The minimum SMF version that this will work with
*/
public $min_smf_version = 'SMF 2.1 Beta 2';
/**
- * Is it supported?
- * @var type
+ * @var bool Whether or not it's supported
*/
public $is_supported = true;
View
30 Sources/Class-TOTP.php
@@ -23,35 +23,34 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class Auth
+ * @package TOTP
+ */
class Auth
{
/**
- * Internal lookup table
- * @var array
+ * @var array Internal lookup table
*/
private $lookup = array();
/**
- * Initialization key
- * @var string
+ * @var string Initialization key
*/
private $initKey = null;
/**
- * Seconds between key refreshes
- * @var integer
+ * @var integer Seconds between key refreshes
*/
private $refreshSeconds = 30;
/**
- * Length of codes to generate
- * @var integer
+ * @var integer The length of codes to generate
*/
private $codeLength = 6;
/**
- * Range plus/minus for "window of opportunity" on allowed codes
- * @var integer
+ * @var integer Range plus/minus for "window of opportunity" on allowed codes
*/
private $range = 2;
@@ -72,8 +71,6 @@ public function __construct($initKey = null)
/**
* Build the base32 lookup table
- *
- * @return null
*/
public function buildLookup()
{
@@ -280,7 +277,7 @@ public function generateCode($length = 16)
}
/**
- * Geenrate the timestamp for the calculation
+ * Generate the timestamp for the calculation
*
* @return integer Timestamp
*/
@@ -310,7 +307,7 @@ public function truncateHash($hash)
/**
* Base32 decoding function
*
- * @param string base32 encoded hash
+ * @param string $hash The base32-encoded hash
* @throws \InvalidArgumentException When hash is not valid
* @return string Binary value of hash
*/
@@ -344,8 +341,9 @@ public function base32_decode($hash)
/**
* Returns a URL to QR code for embedding the QR code
*
- * @param string Generated code
- * @return string URL
+ * @param string $name The name
+ * @param string $code The generated code
+ * @return string The URL to the QR code
*/
public function getQrCodeUrl($name, $code)
{
View
5 Sources/Display.php
@@ -26,6 +26,7 @@
* It jumps to the correct post depending on a number/time/IS_MSG passed.
* It depends on the messages_per_page, defaultMaxMessages and enableAllMessages settings.
* It is accessed by ?topic=id_topic.START.
+ * @return void
*/
function Display()
{
@@ -1848,8 +1849,8 @@ function loadAttachmentContext($id_msg)
/**
* A sort function for putting unapproved attachments first.
- * @param $a An array of info about one attachment
- * @param $b An array of info about a second attachment
+ * @param array $a An array of info about one attachment
+ * @param array $b An array of info about a second attachment
* @return int -1 if $a is approved but $b isn't, 0 if both are approved/unapproved, 1 if $b is approved but a isn't
*/
function approved_attach_sort($a, $b)
View
2  Sources/Drafts.php
@@ -25,7 +25,7 @@
* Determines if this is a new or an existing draft
* Returns errors in $post_errors for display in the template
*
- * @param string $post_errors Any errors encountered trying to save this draft
+ * @param string[] $post_errors Any errors encountered trying to save this draft
* @return boolean Always returns true
*/
function SaveDraft(&$post_errors)
View
4 Sources/Errors.php
@@ -458,8 +458,8 @@ function display_loadavg_error()
/**
* Small utility function for fatal error pages.
- * Used by display_db_error(), display_loadavg_error(),
- * display_maintenance_message()
+ * Used by {@link display_db_error()}, {@link display_loadavg_error()},
+ * {@link display_maintenance_message()}
*/
function set_fatal_error_headers()
{
View
6 Sources/Groups.php
@@ -787,9 +787,9 @@ function GroupRequests()
/**
* Callback function for createList().
*
- * @param $where
- * @param $where_parameters
- * @return int, the count of group requests
+ * @param string $where The WHERE clause for the query
+ * @param array $where_parameters The parameters for the WHERE clause
+ * @return int The number of group requests
*/
function list_getGroupRequestCount($where, $where_parameters)
{
View
6 Sources/Help.php
@@ -39,6 +39,9 @@ function ShowHelp()
call_helper($subActions[$sa]);
}
+/**
+ * The main page for the Help section
+ */
function HelpIndex()
{
global $scripturl, $context, $txt;
@@ -74,6 +77,9 @@ function HelpIndex()
$context['sub_template'] = 'manual';
}
+/**
+ * Displays forum rules
+ */
function HelpRules()
{
global $context, $txt, $boarddir, $user_info, $scripturl;
View
10 Sources/Likes.php
@@ -16,6 +16,9 @@
if (!defined('SMF'))
die('No direct access...');
+/**
+ * Class Likes
+ */
class Likes
{
/**
@@ -114,8 +117,6 @@ public function __construct()
*
* The main handler. Verifies permissions (whether the user can see the content in question), dispatch different method for different sub-actions.
* Accessed from index.php?action=likes
- * @param
- * @return
*/
public function call()
{
@@ -161,7 +162,7 @@ public function call()
* A simple getter for all protected properties.
* Accessed from index.php?action=likes
* @param string $property The name of the property to get.
- * @return mixed either return the property or false if there isn't a property with that name.
+ * @return mixed Either return the property or false if there isn't a property with that name.
*/
public function get($property = '')
{
@@ -598,6 +599,9 @@ protected function response()
}
}
+ /**
+ * Outputs a JSON-encoded response
+ */
protected function jsonResponse()
{
global $modSettings;
View
18 Sources/Load.php
@@ -18,7 +18,6 @@
/**
* Load the $modSettings array.
- *
*/
function reloadSettings()
{
@@ -962,7 +961,6 @@ function loadBoard()
/**
* Load this user's permissions.
- *
*/
function loadPermissions()
{
@@ -1466,7 +1464,7 @@ function loadMemberContext($user, $display_custom_fields = false)
* Loads the user's custom profile fields
*
* @param integer|array $users A single user ID or an array of user IDs
- * @param string|array $param Either a string or an array of strings with profile field names
+ * @param string|array $params Either a string or an array of strings with profile field names
* @return array|boolean An array of data about the fields and their values or false if nothing was loaded
*/
function loadMemberCustomFields($users, $params)
@@ -1536,8 +1534,7 @@ function loadMemberCustomFields($users, $params)
/**
* Loads information about what browser the user is viewing with and places it in $context
- * - uses the class from Class-BrowserDetect.php
- *
+ * - uses the class from {@link Class-BrowserDetect.php}
*/
function detectBrowser()
{
@@ -1551,6 +1548,7 @@ function detectBrowser()
*
* Wrapper function for detectBrowser
* @param string $browser The browser we are checking for.
+ * @return bool Whether or not the current browser is what we're looking for
*/
function isBrowser($browser)
{
@@ -2145,7 +2143,7 @@ function triggerCron()
* @param string $template_name The name of the template to load
* @param array|string $style_sheets The name of a single stylesheet or an array of names of stylesheets to load
* @param bool $fatal If true, dies with an error message if the template cannot be found
- * @return boolean True if the template was loaded, false otherwise
+ * @return boolean Whether or not the template was loaded
*/
function loadTemplate($template_name, $style_sheets = array(), $fatal = true)
{
@@ -2226,7 +2224,7 @@ function loadTemplate($template_name, $style_sheets = array(), $fatal = true)
* @todo get rid of reading $_REQUEST directly
*
* @param string $sub_template_name The name of the sub-template to load
- * @param bool Whether to die with an error if the sub-template can't be loaded
+ * @param bool $fatal Whether to die with an error if the sub-template can't be loaded
*/
function loadSubTemplate($sub_template_name, $fatal = false)
{
@@ -2309,6 +2307,7 @@ function loadCSSFile($filename, $params = array(), $id = '')
* - all code added with this function is added to the same <style> tag so do make sure your css is valid!
*
* @param string $css Some css code
+ * @return void|bool Adds the CSS to the $context['css_header'] array or returns if no CSS is specified
*/
function addInlineCss($css)
{
@@ -2395,7 +2394,8 @@ function addJavascriptVar($key, $value, $escape = false)
* - all code added with this function is added to the same <script> tag so do make sure your JS is clean!
*
* @param string $javascript Some JS code
- * @param bool Whether the script should load in <head> or before the closing <html> tag
+ * @param bool $defer Whether the script should load in <head> or before the closing <html> tag
+ * @return void|bool Adds the code to one of the $context['javascript_inline'] arrays or returns if no JS was specified
*/
function addInlineJavascript($javascript, $defer = false)
{
@@ -3292,7 +3292,7 @@ function get_memcached_server($level = 3)
* - filename The attachment filename
*
* @param array $data An array of raw info
- * @return array
+ * @return array An array of avatar data
*/
function set_avatar_data($data = array())
{
View
24 Sources/LogInOut.php
@@ -633,8 +633,8 @@ function DoLogin()
* It redirects back to $_SESSION['logout_url'], if it exists.
* It is accessed via ?action=logout;session_var=...
*
- * @param bool $internal if true, it doesn't check the session
- * @param $redirect
+ * @param bool $internal If true, it doesn't check the session
+ * @param bool $redirect Whether or not to redirect the user after they log out
*/
function Logout($internal = false, $redirect = true)
{
@@ -714,9 +714,9 @@ function Logout($internal = false, $redirect = true)
/**
* MD5 Encryption used for older passwords. (SMF 1.0.x/YaBB SE 1.5.x hashing)
*
- * @param string $data
- * @param string $key
- * @return string, the HMAC MD5 of data with key
+ * @param string $data The data
+ * @param string $key The key
+ * @return string The HMAC MD5 of data with key
*/
function md5_hmac($data, $key)
{
@@ -727,9 +727,9 @@ function md5_hmac($data, $key)
/**
* Custom encryption for phpBB3 based passwords.
*
- * @param string $passwd
- * @param string $passwd_hash
- * @return string
+ * @param string $passwd The raw (unhashed) password
+ * @param string $passwd_hash The hashed password
+ * @return string The hashed version of $passwd
*/
function phpBB3_password_check($passwd, $passwd_hash)
{
@@ -784,10 +784,10 @@ function phpBB3_password_check($passwd, $passwd_hash)
* This protects against brute force attacks on a member's password.
* Importantly, even if the password was right we DON'T TELL THEM!
*
- * @param $id_member
- * @param $password_flood_value = false
- * @param $was_correct = false
- * @param $tfa = false;
+ * @param int $id_member The ID of the member
+ * @param bool|string $password_flood_value False if we don't have a flood value, otherwise a string with a timestamp and number of tries separated by a |
+ * @param bool $was_correct Whether or not the password was correct
+ * @param bool $tfa Whether we're validating for two-factor authentication
*/
function validatePasswordFlood($id_member, $password_flood_value = false, $was_correct = false, $tfa = false)
{
View
17 Sources/Logging.php
@@ -19,7 +19,7 @@
/**
* Put this user in the online log.
*
- * @param bool $force = false
+ * @param bool $force Whether to force logging the data
*/
function writeLog($force = false)
{
@@ -326,8 +326,8 @@ function displayDebug()
* It does not actually commit the changes until the end of the page view.
* It depends on the trackStats setting.
*
- * @param array $stats = array()
- * @return boolean|array
+ * @param array $stats An array of data
+ * @return bool Whether or not the info was updated successfully
*/
function trackStats($stats = array())
{
@@ -386,9 +386,10 @@ function trackStats($stats = array())
* You should use {@link logActions()} instead.
* @example logAction('remove', array('starter' => $id_member_started));
*
- * @param string $action
- * @param array $extra = array()
- * @param string $log_type options: 'moderate', 'admin', ...etc.
+ * @param string $action The action to log
+ * @param array $extra = array() An array of additional data
+ * @param string $log_type What type of log ('admin', 'moderate', etc.)
+ * @return int The ID of the row containing the logged data
*/
function logAction($action, $extra = array(), $log_type = 'moderate')
{
@@ -403,8 +404,8 @@ function logAction($action, $extra = array(), $log_type = 'moderate')
* Log changes to the forum, such as moderation events or administrative changes.
* This behaves just like logAction() in SMF 2.0, except that it is designed to log multiple actions at once.
*
- * @param array $logs
- * @return the last logged ID
+ * @param array $logs An array of log data
+ * @return int The last logged ID
*/
function logActions($logs)
{
View
37 Sources/ManageAttachments.php
@@ -80,7 +80,8 @@ function ManageAttachments()
* This is the default sub-action of the 'Attachments and Avatars' center.
* Called by index.php?action=admin;area=manageattachments;sa=attachments.
*
- * @param bool $return_config = false
+ * @param bool $return_config Whether to return the array of config variables (used for admin search)
+ * @return void|array If $return_config is true, simply returns the config_vars array, otherwise returns nothing
* @uses 'attachments' sub template.
*/
@@ -265,7 +266,8 @@ function ManageAttachmentSettings($return_config = false)
* Show/set permissions for permissions: 'profile_server_avatar',
* 'profile_upload_avatar' and 'profile_remote_avatar'.
*
- * @param bool $return_config = false
+ * @param bool $return_config Whether to return the config_vars array (used for admin search)
+ * @return void|array Returns the config_vars array if $return_config is true, otherwise returns nothing
* @uses 'avatars' sub template.
*/
function ManageAvatarSettings($return_config = false)
@@ -603,10 +605,11 @@ function BrowseFiles()
* 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 int $start The item to start with
+ * @param int $items_per_page How many items to show per page
+ * @param string $sort A string indicating how to sort results
* @param string $browse_type can be one of 'avatars' or ... not. :P
+ * @return array An array of file info
*/
function list_getFiles($start, $items_per_page, $sort, $browse_type)
{
@@ -666,6 +669,7 @@ function list_getFiles($start, $items_per_page, $sort, $browse_type)
* (the specified type being attachments or avatars).
*
* @param string $browse_type can be one of 'avatars' or not. (in which case they're attachments)
+ * @return int The number of files
*/
function list_getNumFiles($browse_type)
{
@@ -958,10 +962,11 @@ function RemoveAllAttachments()
* It does no permissions check.
* @internal
*
- * @param array $condition
- * @param string $query_type
- * @param bool $return_affected_messages = false
- * @param bool $autoThumbRemoval = true
+ * @param array $condition An array of conditions
+ * @param string $query_type The query type. Can be 'messages' or 'members'
+ * @param bool $return_affected_messages Whether to return an array with the IDs of affected messages
+ * @param bool $autoThumbRemoval Whether to automatically remove any thumbnails associated with the removed files
+ * @return void|int[] Returns an array containing IDs of affected messages if $return_affected_messages is true
*/
function removeAttachments($condition, $query_type = '', $return_affected_messages = false, $autoThumbRemoval = true)
{
@@ -1680,8 +1685,8 @@ function RepairAttachments()
* Called by repairAttachments().
* If repairAttachments() has more steps added, this function needs updated!
*
- * @param array $to_fix attachments to fix
- * @param int $max_substep = 0
+ * @param array $to_fix IDs of attachments to fix
+ * @param int The maximum substep to reach before pausing
*/
function pauseAttachmentMaintenance($to_fix, $max_substep = 0)
{
@@ -1811,7 +1816,8 @@ function ApproveAttach()
/**
* Approve an attachment, or maybe even more - no permission check!
*
- * @param array $attachments
+ * @param array $attachments The IDs of the attachments to approve
+ * @return void|int Returns 0 if the operation failed, otherwise returns nothing
*/
function ApproveAttachments($attachments)
{
@@ -2429,6 +2435,7 @@ function ManageAttachmentPaths()
/**
* Prepare the actual attachment directories to be displayed in the list.
+ * @return array An array of information about the attachment directories
*/
function list_getAttachDirs()
{
@@ -2507,6 +2514,7 @@ function list_getAttachDirs()
/**
* Prepare the base directories to be displayed in a list.
+ * @return void|array Returns nothing if there are no base directories, otherwise returns an array of info about the directories
*/
function list_getBaseDirs()
{
@@ -2558,8 +2566,9 @@ function list_getBaseDirs()
* of the status key, if that status key signifies an error, and
* the file count.
*
- * @param string $dir
- * @param int $expected_files
+ * @param string $dir The directory to check
+ * @param int $expected_files How many files should be in that directory
+ * @return array An array containing the status of the directory, whether the number of files was what we expected and how many were in the directory
*/
function attachDirStatus($dir, $expected_files)
{
View
137 Sources/ManageBans.php
@@ -286,10 +286,10 @@ function BanList()
/**
* Get bans, what else? For the given options.
*
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
- * @return array
+ * @param int $start Which item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param string $sort A string telling ORDER BY how to sort the results
+ * @return array An array of information about the bans for the list
*/
function list_getBans($start, $items_per_page, $sort)
{
@@ -320,7 +320,7 @@ function list_getBans($start, $items_per_page, $sort)
/**
* Get the total number of ban from the ban group table
*
- * @return int
+ * @return int The total number of bans
*/
function list_getNumBans()
{
@@ -592,11 +592,11 @@ function BanEdit()
/**
* Retrieves all the ban items belonging to a certain ban group
*
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
- * @param int $ban_group_id
- * @return array
+ * @param int $start Which item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param int $sort Not used here
+ * @param int $ban_group_id The ID of the group to get the bans for
+ * @return array An array with information about the returned ban items
*/
function list_getBanItems($start = 0, $items_per_page = 0, $sort = 0, $ban_group_id = 0)
{
@@ -696,7 +696,7 @@ function list_getBanItems($start = 0, $items_per_page = 0, $sort = 0, $ban_group
/**
* Gets the number of ban items belonging to a certain ban group
*
- * @return int
+ * @return int The number of ban items
*/
function list_getNumBanItems()
{
@@ -723,8 +723,8 @@ function list_getNumBanItems()
/**
* Finds additional IPs related to a certain user
*
- * @param int $member_id
- * @return array
+ * @param int $member_id The ID of the member to get additional IPs for
+ * @return array An containing two arrays - ips_in_messages (IPs used in posts) and ips_in_errors (IPs used in error messages)
*/
function banLoadAdditionalIPs($member_id)
{
@@ -743,6 +743,10 @@ function banLoadAdditionalIPs($member_id)
return $return;
}
+/**
+ * @param int $member_id The ID of the member
+ * @return array An array of IPs used in posts by this member
+ */
function banLoadAdditionalIPsMember($member_id)
{
global $smcFunc;
@@ -767,6 +771,10 @@ function banLoadAdditionalIPsMember($member_id)
return $message_ips;
}
+/**
+ * @param int $member_id The ID of the member
+ * @return array An array of IPs associated with error messages generated by this user
+ */
function banLoadAdditionalIPsError($member_id)
{
global $smcFunc;
@@ -879,12 +887,12 @@ function banEdit2()
* Saves one or more ban triggers into a ban item: according to the suggestions
* checks the $_POST variable to verify if the trigger is present
*
- * @param array $suggestions
- * @param int $ban_group
- * @param int $member
- * @param int $ban_id
+ * @param array $suggestions An array of suggestedtriggers (IP, email, etc.)
+ * @param int $ban_group The ID of the group we're saving bans for
+ * @param int $member The ID of the member associated with this ban (if applicable)
+ * @param int $ban_id The ID of the ban (0 if this is a new ban)
*
- * @return mixed array with the saved triggers or false on failure
+ * @return array|bool An array with the triggers if there were errors or false on success
*/
function saveTriggers($suggestions = array(), $ban_group, $member = 0, $ban_id = 0)
{
@@ -926,8 +934,9 @@ function saveTriggers($suggestions = array(), $ban_group, $member = 0, $ban_id =
* This function removes a bunch of triggers based on ids
* Doesn't clean the inputs
*
- * @param array $items_ids
- * @return bool
+ * @param array $items_ids The items to remove
+ * @param bool|int $group_id The ID of the group these triggers are associated with or false if deleting them from all groups
+ * @return bool Always returns true
*/
function removeBanTriggers($items_ids = array(), $group_id = false)
{
@@ -1050,8 +1059,8 @@ function removeBanTriggers($items_ids = array(), $group_id = false)
* This function removes a bunch of ban groups based on ids
* Doesn't clean the inputs
*
- * @param array $group_ids
- * @return bool
+ * @param int[] $group_ids The IDs of the groups to remove
+ * @return bool Returns ture if successful or false if $group_ids is empty
*/
function removeBanGroups($group_ids)
{
@@ -1080,8 +1089,8 @@ function removeBanGroups($group_ids)
* Removes logs - by default truncate the table
* Doesn't clean the inputs
*
- * @param array (optional) $ids
- * @return bool
+ * @param array $ids Empty array to clear the ban log or the IDs of the log entries to remove
+ * @return bool Returns true if successful or false if $ids is invalid
*/
function removeBanLogs($ids = array())
{
@@ -1120,8 +1129,8 @@ function removeBanLogs($ids = array())
*
* Errors in $context['ban_errors']
*
- * @param array $triggers
- * @return array triggers and logs info ready to be used
+ * @param array $triggers The triggers to validate
+ * @return array An array of riggers and log info ready to be used
*/
function validateTriggers(&$triggers)
{
@@ -1292,10 +1301,10 @@ function validateTriggers(&$triggers)
*
* Errors in $context['ban_errors']
*
- * @param int $group_id
- * @param array $triggers
- * @param array $logs
- * @return nothing
+ * @param int $group_id The ID of the group to add the triggers to (0 to create a new one)
+ * @param array $triggers The triggers to add
+ * @param array $logs The log data
+ * @return bool Whether or not the action was successful
*/
function addTriggers($group_id = 0, $triggers = array(), $logs = array())
{
@@ -1385,11 +1394,10 @@ function addTriggers($group_id = 0, $triggers = array(), $logs = array())
*
* Errors in $context['ban_errors']
*
- * @param int $ban_item
- * @param int $group_id
- * @param array $trigger
- * @param array $logs
- * @return nothing
+ * @param int $ban_item The ID of the ban item
+ * @param int $group_id The ID of the ban group
+ * @param array $trigger An array of triggers
+ * @param array $logs An array of log info
*/
function updateTriggers($ban_item = 0, $group_id = 0, $trigger = array(), $logs = array())
{
@@ -1460,8 +1468,8 @@ function updateTriggers($ban_item = 0, $group_id = 0, $trigger = array(), $logs
* @param array $logs an array of logs, each log contains the following keys:
* - bantype: a known type of ban (ip_range, hostname, email, user, main_ip)
* - value: the value of the bantype (e.g. the IP or the email address banned)
- * @param bool $new if the trigger is new or an update of an existing one
- * @param bool $removal if the trigger is being deleted
+ * @param bool $new Whether the trigger is new or an update of an existing one
+ * @param bool $removal Whether the trigger is being deleted
*/
function logTriggersUpdates($logs, $new = true, $removal = false)
{
@@ -1491,8 +1499,7 @@ function logTriggersUpdates($logs, $new = true, $removal = false)
*
* Errors in $context['ban_errors']
*
- * @param array $ban_info
- * @return nothing
+ * @param array $ban_info An array of info about the ban group. Should have name and may also have an id.
*/
function updateBanGroup($ban_info = array())
{
@@ -1579,8 +1586,8 @@ function updateBanGroup($ban_info = array())
*
* Errors in $context['ban_errors']
*
- * @param array $ban_info
- * @return int the ban group's ID
+ * @param array $ban_info An array containing 'name', which is the name of the ban group
+ * @return int The ban group's ID
*/
function insertBanGroup($ban_info = array())
{
@@ -1952,13 +1959,13 @@ function BanBrowseTriggers()
}
/**
- * Get ban triggers for the given parameters.
+ * Get ban triggers for the given parameters. Callback from $listOptions['get_items'] in BanBrowseTriggers()
*
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
- * @param string $trigger_type
- * @return array
+ * @param int $start The item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param string $sort A string telling ORDER BY how to sort the results
+ * @param string $trigger_type The trigger type - can be 'ip', 'hostname' or 'email'
+ * @return array An array of ban trigger info for the list
*/
function list_getBanTriggers($start, $items_per_page, $sort, $trigger_type)
{
@@ -1994,10 +2001,10 @@ function list_getBanTriggers($start, $items_per_page, $sort, $trigger_type)
}
/**
- * This returns the total number of ban triggers of the given type.
+ * This returns the total number of ban triggers of the given type. Callback for $listOptions['get_count'] in BanBrowseTriggers().
*
- * @param string $trigger_type
- * @return int
+ * @param string $trigger_type The trigger type. Can be 'ip', 'hostname' or 'email'
+ * @return int The number of triggers of the specified type
*/
function list_getNumBanTriggers($trigger_type)
{
@@ -2179,11 +2186,12 @@ function BanLog()
/**
* Load a list of ban log entries from the database.
- * (no permissions check)
+ * (no permissions check). Callback for $listOptions['get_items'] in BanLog()
*
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
+ * @param int $start The item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param string $sort A string telling ORDER BY how to sort the results
+ * @return array An array of info about the ban log entries for the list.
*/
function list_getBanLogEntries($start, $items_per_page, $sort)
{
@@ -2209,7 +2217,8 @@ function list_getBanLogEntries($start, $items_per_page, $sort)
}
/**
- * This returns the total count of ban log entries.
+ * This returns the total count of ban log entries. Callback for $listOptions['get_count'] in BanLog().
+ * @return int The total number of ban log entries.
*/
function list_getNumBanLogEntries()
{
@@ -2234,9 +2243,9 @@ function list_getNumBanLogEntries()
* @example
* range2ip(array(10, 10, 10, 0), array(10, 10, 20, 255)) returns '10.10.10-20.*
*
- * @param array $low IPv4 format
- * @param array $high IPv4 format
- * @return string
+ * @param array $low The low end of the range in IPv4 format
+ * @param array $high The high end of the range in IPv4 format
+ * @return string A string indicating the range
*/
function range2ip($low, $high)
{
@@ -2287,9 +2296,9 @@ function range2ip($low, $high)
* If yes, it returns an error message. Otherwise, it returns an array
* optimized for the database.
*
- * @param array $ip_array
- * @param string $fullip
- * @return boolean
+ * @param array $ip_array An array of IP trigger data
+ * @param string $fullip The full IP
+ * @return boolean|array False if the trigger array is invalid or the passed array if the value doesn't exist in the database
*/
function checkExistingTriggerIP($ip_array, $fullip = '')
{
@@ -2479,6 +2488,12 @@ function updateBanMembers()
updateStats('member');
}
+/**
+ * Gets basic member data for the ban
+ *
+ * @param int $id The ID of the member to get data for
+ * @return array An aray containing the ID, name, main IP and email address of the specified user
+ */
function getMemberData($id)
{
global $smcFunc;
View
4 Sources/ManageBoards.php
@@ -371,7 +371,6 @@ function EditCategory2()
* 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).
-
*/
function EditBoard()
{
@@ -816,7 +815,8 @@ function ModifyCat()
* A screen to set a few general board and category settings.
*
* @uses modify_general_settings sub-template.
- * @param $return_config
+ * @param bool $return_config Whether to return the $config_vars array (used for admin search)
+ * @return void|array Returns nothing or the array of config vars if $return_config is true
*/
function EditBoardSettings($return_config = false)
{
View
3  Sources/ManageCalendar.php
@@ -303,7 +303,8 @@ function EditHoliday()
/**
* Show and allow to modify calendar settings. Obviously.
*
- * @param bool $return_config = false
+ * @param bool $return_config Whether to return the $config_vars array (used for admin search)
+ * @return void|array Returns nothing or returns $config_vars if $return_config is true
*/
function ModifyCalendarSettings($return_config = false)
{
View
12 Sources/ManageLanguages.php
@@ -139,7 +139,7 @@ function AddLanguage()
* Gets a list of available languages from the mother ship
* Will return a subset if searching, otherwise all avaialble
*
- * @return string
+ * @return array An array containing information about each available language
*/
function list_getLanguagesList()
{
@@ -697,6 +697,7 @@ function highlightSelected(box)
/**
* How many languages?
* Callback for the list in ManageLanguageSettings().
+ * @return int The number of available languages
*/
function list_getNumLanguages()
{
@@ -708,6 +709,7 @@ function list_getNumLanguages()
* Callback for $listOptions['get_items']['function'] in ManageLanguageSettings.
* Determines which languages are available by looking for the "index.{language}.php" file.
* Also figures out how many users are using a particular language.
+ * @return array An array of information about currenty installed languages
*/
function list_getLanguages()
{
@@ -777,7 +779,8 @@ function list_getLanguages()
/**
* Edit language related settings.
*
- * @param bool $return_config = false
+ * @param bool $return_config Whether to return the $config_vars array (used in admin search)
+ * @return void|array Returns nothing or the $config_vars array if $return_config is true
*/
function ModifyLanguageSettings($return_config = false)
{
@@ -1236,8 +1239,9 @@ function ModifyLanguage()
* This function cleans language entries to/from display.
* @todo This function could be two functions?
*
- * @param $string
- * @param $to_display
+ * @param string $string The language string
+ * @param bool $to_display Whether or not this is going to be displayed
+ * @return string The cleaned string
*/
function cleanLangString($string, $to_display = true)
{
View
20 Sources/ManageMail.php
@@ -218,11 +218,12 @@ function BrowseMailQueue()
/**
* This function grabs the mail queue items from the database, according to the params given.
+ * Callback for $listOptions['get_items'] in BrowseMailQueue()
*
- * @param int $start
- * @param int $items_per_page
- * @param string $sort
- * @return array
+ * @param int $start The item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param string $sort A string indicating how to sort the results
+ * @return array An array with info about the mail queue items
*/
function list_getMailQueue($start, $items_per_page, $sort)
{
@@ -256,7 +257,8 @@ function list_getMailQueue($start, $items_per_page, $sort)
/**
* Returns the total count of items in the mail queue.
- * @return int
+ * Callback for $listOptions['get_count'] in BrowseMailQueue
+ * @return int The total number of mail queue items
*/
function list_getMailQueueSize()
{
@@ -278,8 +280,8 @@ function list_getMailQueueSize()
/**
* Allows to view and modify the mail settings.
*
- * @param bool $return_config = false
- * @return array
+ * @param bool $return_config Whether to return the $config_vars array (used for admin search)
+ * @return void|array Returns nothing or returns the $config_vars array if $return_config is true
*/
function ModifyMailSettings($return_config = false)
{
@@ -450,8 +452,8 @@ function pauseMailQueueClear()
/**
* Little utility function to calculate how long ago a time was.
*
- * @param long $time_diff
- * @return string
+ * @param int $time_diff The time difference, in seconds
+ * @return string A string indicating how many days, hours, minutes or seconds (depending on $time_diff)
*/
function time_since($time_diff)
{
View
19 Sources/ManageMaintenance.php
@@ -2348,8 +2348,8 @@ function list_integration_hooks()
/**
* Gets all of the files in a directory and its children directories
*
- * @param type $dir_path
- * @return array
+ * @param string $dir_path The path to the directory
+ * @return array An array containing information about the files found in the specified directory and its children
*/
function get_files_recursive($dir_path)
{
@@ -2376,12 +2376,11 @@ function get_files_recursive($dir_path)
/**
* Callback function for the integration hooks list (list_integration_hooks)
* Gets all of the hooks in the system and their status
- * Would be better documented if Ema was not lazy
*
- * @param type $start
- * @param type $per_page
- * @param type $sort
- * @return array
+ * @param int $start The item to start with (for pagination purposes)
+ * @param int $per_page How many items to display on each page
+ * @param string $sort A string indicating how to sort things
+ * @return array An array of information about the integration hooks
*/
function get_integration_hooks_data($start, $per_page, $sort)
{
@@ -2562,8 +2561,7 @@ function get_integration_hooks_data($start, $per_page, $sort)
* Simply returns the total count of integration hooks
* Used by the integration hooks list function (list_integration_hooks)
*
- * @global type $context
- * @return int
+ * @return int The number of hooks currently in use
*/
function get_integration_hooks_count()
{
@@ -2588,8 +2586,7 @@ function get_integration_hooks_count()
/**
* Parses modSettings to create integration hook array
*
- * @staticvar type $integration_hooks
- * @return type
+ * @return array An array of information about the integration hooks
*/
function get_integration_hooks()
{
View
4 Sources/ManageMembers.php
@@ -1263,8 +1263,8 @@ function AdminApprove()
* 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.
+ * @param int $old The timestamp of the old date
+ * @return int The number of days since $old, based on the forum time
*/
function jeffsdatediff($old)
{
View
7 Sources/ManageNews.php
@@ -272,7 +272,7 @@ function addNewsItem ()
/**
* Prepares an array of the forum news items for display in the template
*
- * @return array
+ * @return array An array of information about the news items
*/
function list_getNews()
{
@@ -688,7 +688,7 @@ function ComposeMailing()
* Redirects to itself when more batches need to be sent.
* Redirects to ?action=admin;area=news;sa=mailingmembers after everything has been sent.
*
- * @param bool $clean_only = false; if set, it will only clean the variables, put them in context, then return.
+ * @param bool $clean_only 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)
@@ -1046,7 +1046,8 @@ function SendMailing($clean_only = false)
* Requires the forum_admin permission.
*
* @uses ManageNews template, news_settings sub-template.
- * @param bool $return_config = false
+ * @param bool $return_config Whether or not to return the config_vars array (used for admin search)
+ * @return void|array Returns nothing or returns the config_vars array if $return_config is true
*/
function ModifyNewsSettings($return_config = false)
{
View
43 Sources/ManagePaid.php
@@ -81,7 +81,8 @@ function ManagePaidSubscriptions()
* It requires the moderate_forum permission
* Accessed from ?action=admin;area=paidsubscribe;sa=settings.
*
- * @param bool $return_config = false
+ * @param bool $return_config Whether or not to return the $config_vars array (used for admin search)
+ * @return void|array Returns nothing or returns the config_vars array if $return_config is true
*/
function ModifySubscriptionSettings($return_config = false)
{
@@ -948,9 +949,10 @@ function ViewSubscribedUsers()
* 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()
+ * @param int $id_sub The ID of the subscription
+ * @param string $search_string A search string
+ * @param array $search_vars An array of variables for the search string
+ * @return int The number of subscribed users matching the given parameters
*/
function list_getSubscribedUserCount($id_sub, $search_string, $search_vars = array())
{
@@ -979,12 +981,13 @@ function list_getSubscribedUserCount($id_sub, $search_string, $search_vars = arr
* 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
+ * @param int $start The item to start with (for pagination purposes)
+ * @param int $items_per_page How many items to show on each page
+ * @param string $sort A string indicating how to sort the results
+ * @param int $id_sub The ID of the subscription
+ * @param string $search_string A search string
+ * @param array $search_vars The variables for the search string
+ * @return array An array of information about the subscribed users matching the given parameters
*/
function list_getSubscribedUsers($start, $items_per_page, $sort, $id_sub, $search_string, $search_vars = array())
{
@@ -1361,7 +1364,7 @@ function ModifyUserSubscription()
/**
* Reapplies all subscription rules for each of the users.
*
- * @param array $users
+ * @param array $users An array of user IDs
*/
function reapplySubscriptions($users)
{
@@ -1444,11 +1447,11 @@ function reapplySubscriptions($users)
/**
* 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
+ * @param int $id_subscribe The subscription ID
+ * @param int $id_member The ID of the member
+ * @param int|string $renewal 0 if we're forcing start/end time, otherwise a string indicating how long to renew the subscription for ('D', 'W', 'M' or 'Y')
+ * @param int $forceStartTime If set, forces the subscription to start at the specified time
+ * @param int $forceEndTime If set, forces the subscription to end at the specified time
*/
function addSubscription($id_subscribe, $id_member, $renewal = 0, $forceStartTime = 0, $forceEndTime = 0)
{
@@ -1666,9 +1669,9 @@ function addSubscription($id_subscribe, $id_member, $renewal = 0, $forceStartTim
/**
* Removes a subscription from a user, as in removes the groups.
*
- * @param $id_subscribe
- * @param $id_member
- * @param $delete
+ * @param int $id_subscribe The ID of the subscription
+ * @param int $id_member The ID of the member
+ * @param bool $delete Whether to delete the subscription or just disable it
*/
function removeSubscription($id_subscribe, $id_member, $delete = false)
{
@@ -1933,7 +1936,7 @@ function loadSubscriptions()
* 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
+ * @return array An array of information about available payment gateways
*/
function loadPaymentGateways()
{
View
6 Sources/tasks/ApprovePost-Notify.php
@@ -12,8 +12,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class ApprovePost_Notify_Background
+ */
class ApprovePost_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $scripturl, $modSettings, $language;
View
6 Sources/tasks/ApproveReply-Notify.php
@@ -12,8 +12,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class ApproveReply_Notify_Background
+ */
class ApproveReply_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $scripturl, $modSettings, $language;
View
6 Sources/tasks/Buddy-Notify.php
@@ -13,8 +13,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class Buddy_Notify_Background
+ */
class Buddy_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir;
View
6 Sources/tasks/CreatePost-Notify.php
@@ -12,8 +12,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class CreatePost_Notify_Background
+ */
class CreatePost_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $scripturl, $language, $modSettings, $language;
View
6 Sources/tasks/EventNew-Notify.php
@@ -14,8 +14,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class EventNew_Notify_Background
+ */
class EventNew_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $sourcedir, $smcFunc, $user_profile;
View
6 Sources/tasks/GroupReq-Notify.php
@@ -14,8 +14,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class GroupReq_Notify_Background
+ */
class GroupReq_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $sourcedir, $smcFunc, $language, $modSettings, $scripturl;
View
6 Sources/tasks/Likes-Notify.php
@@ -13,8 +13,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class Likes_Notify_Background
+ */
class Likes_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir;
View
6 Sources/tasks/MemberReport-Notify.php
@@ -13,8 +13,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class MemberReport_Notify_Background
+ */
class MemberReport_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $modSettings, $language, $scripturl;
View
6 Sources/tasks/MemberReportReply-Notify.php
@@ -14,8 +14,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class MemberReportReply_Notify_Background
+ */
class MemberReportReply_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $modSettings, $language, $scripturl;
View
6 Sources/tasks/MsgReport-Notify.php
@@ -13,8 +13,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class MsgReport_Notify_Background
+ */
class MsgReport_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $modSettings, $language, $scripturl;
View
6 Sources/tasks/MsgReportReply-Notify.php
@@ -14,8 +14,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class MsgReportReply_Notify_Background
+ */
class MsgReportReply_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $modSettings, $language, $scripturl;
View
6 Sources/tasks/Register-Notify.php
@@ -13,8 +13,14 @@
* @version 2.1 Beta 2
*/
+/**
+ * Class Register_Notify_Background
+ */
class Register_Notify_Background extends SMF_BackgroundTask
{
+ /**
+ * @return bool
+ */
public function execute()
{
global $smcFunc, $sourcedir, $modSettings, $language, $scripturl;
View
37 cron.php
@@ -115,8 +115,10 @@
obExit_cron();
exit;
-// The heart of this cron handler...
-
+/**
+ * The heart of this cron handler...
+ * @return bool|array False if there's nothing to do or an array of info about the task
+ */
function fetch_task()
{
global $smcFunc;
@@ -174,6 +176,11 @@ function fetch_task()
}
}
+/**
+ * This actually handles the task
+ * @param array $task_details An array of info about the task
+ * @return bool|void True if the task is invalid; otherwise calls the function to execute the task
+ */
function perform_task($task_details)
{
global $sourcedir, $boarddir;
@@ -208,6 +215,10 @@ function perform_task($task_details)
}
// These are all our helper functions that resemble their big brother counterparts. These are not so important.
+/**
+ * Cleans up the request variables
+ * @return void
+ */
function cleanRequest_cron()
{
global $scripturl, $boardurl;
@@ -224,6 +235,14 @@ function cleanRequest_cron()
unset($GLOBALS['_GET'], $GLOBALS['_POST'], $GLOBALS['_REQUEST'], $GLOBALS['_COOKIE'], $GLOBALS['_FILES']);
}
+/**
+ * The error handling function
+ * @param int $error_level One of the PHP error level constants (see )
+ * @param string $error_string The error message
+ * @param string $file The file where the error occurred
+ * @param int $line What line of the specified file the error occurred on
+ * @return void
+ */
function error_handler_cron($error_level, $error_string, $file, $line)
{
global $modSettings;
@@ -241,6 +260,9 @@ function error_handler_cron($error_level, $error_string, $file, $line)
die('No direct access...');
}
+/**
+ * The exit function
+ */
function obExit_cron()
{
if (FROM_CLI)
@@ -254,15 +276,26 @@ function obExit_cron()
// We would like this to be defined, but we don't want to have to load more stuff than necessary.
// Thus we declare it here, and any legitimate background task must implement this.
+/**
+ * Class SMF_BackgroundTask
+ */
abstract class SMF_BackgroundTask
{
protected $_details;
+ /**
+ * The constructor.
+ * @param $details The details for the task
+ */
public function __construct($details)
{
$this->_details = $details;
}
+ /**
+ * The function to actually execute a task
+ * @return mixed
+ */
abstract public function execute();
}
?>
View
1  index.php
@@ -159,6 +159,7 @@
/**
* The main dispatcher.
* This delegates to each area.
+ * @return array|string|void An array containing the file to include and name of function to call, the name of a function to call or dies with a fatal_lang_error if we couldn't find anything to do.
*/
function smf_main()
{
View
32 proxy.php
@@ -15,11 +15,29 @@
define('SMF', 'proxy');
+/**
+ * Class ProxyServer
+ */
class ProxyServer
{
+ /**
+ * @var bool $enabled Whether or not this is enabled
+ */
protected $enabled;
+
+ /**
+ * @var int $maxSize The maximum size for files to cache
+ */
protected $maxSize;
+
+ /**
+ * @var string $secret A secret code used for hashing
+ */
protected $secret;
+
+ /**
+ * @var string The cache directory
+ */
protected $cache;
/**
@@ -44,7 +62,7 @@ public function __construct()
* Checks whether the request is valid or not
*
* @access public
- * @return bool
+ * @return bool Whether the request is valid
*/
public function checkRequest()
{
@@ -107,8 +125,8 @@ public function serve()
* Returns the request's hashed filepath
*
* @access public
- * @param string $request
- * @return string
+ * @param string $request The request to get the path for
+ * @return string The hashed filepath for the specified request
*/
protected function getCachedPath($request)
{
@@ -119,8 +137,8 @@ protected function getCachedPath($request)
* Check whether the image exists in local cache or not
*
* @access protected
- * @param string $request
- * @return bool
+ * @param string $request The image to check for in the cache
+ * @return bool Whether or not the requested image is cached
*/
protected function isCached($request)
{
@@ -131,8 +149,8 @@ protected function isCached($request)
* Attempts to cache the image while validating it
*
* @access protected
- * @param string
- * @return bool
+ * @param string $request The image to cache/validate
+ * @return bool Whether the specified image was cached
*/
protected function cacheImage($request)
{
View
3  subscriptions.php
@@ -288,7 +288,8 @@
/**
* Log an error then exit
*
- * @param string $text
+ * @param string $text The error to log
+ * @return void
*/
function generateSubscriptionError($text)
{
Please sign in to comment.
Something went wrong with that request. Please try again.