Merge pull request #2027 from JN-Jones/fix-2026-wrong_doc_blocks

#2026 Wrong Doc Blocks

admin/inc/class_page.php

@@ -67,7 +67,7 @@ class DefaultPage
 	/**
 	 * Output the page header.
 	 *
-	 * @param string The title of the page.
+	 * @param string $title The title of the page.
 	 */
 	function output_header($title="")
 	{
@@ -191,6 +191,8 @@ function output_header($title="")
 
 	/**
 	 * Output the page footer.
+	 *
+	 * @param bool $quit
 	 */
 	function output_footer($quit=true)
 	{
@@ -240,8 +242,8 @@ function output_footer($quit=true)
 	/**
 	 * Add an item to the page breadcrumb trail.
 	 *
-	 * @param string The name of the item to add.
-	 * @param string The URL to the item we're adding (if there is one)
+	 * @param string $name The name of the item to add.
+	 * @param string $url The URL to the item we're adding (if there is one)
 	 */
 	function add_breadcrumb_item($name, $url="")
 	{
@@ -250,6 +252,8 @@ function add_breadcrumb_item($name, $url="")
 
 	/**
 	 * Generate a breadcrumb trail.
+	 *
+	 * @return bool|string
 	 */
 	function _generate_breadcrumb()
 	{
@@ -279,7 +283,7 @@ function _generate_breadcrumb()
 	/**
 	 * Output a success message.
 	 *
-	 * @param string The message to output.
+	 * @param string $message The message to output.
 	 */
 	function output_success($message)
 	{
@@ -289,8 +293,8 @@ function output_success($message)
 	/**
 	 * Output an alert/warning message.
 	 *
-	 * @param string The message to output.
-	 * @param string The ID of the alert/warning (optional)
+	 * @param string $message The message to output.
+	 * @param string $id The ID of the alert/warning (optional)
 	 */
 	function output_alert($message, $id="")
 	{
@@ -304,7 +308,7 @@ function output_alert($message, $id="")
 	/**
 	 * Output an inline message.
 	 *
-	 * @param string The message to output.
+	 * @param string $message The message to output.
 	 */
 	function output_inline_message($message)
 	{
@@ -314,7 +318,7 @@ function output_inline_message($message)
 	/**
 	 * Output a single error message.
 	 *
-	 * @param string The message to output.
+	 * @param string $error The message to output.
 	 */
 	function output_error($error)
 	{
@@ -326,7 +330,7 @@ function output_error($error)
 	/**
 	 * Output one or more inline error messages.
 	 *
-	 * @param array Array of error messages to output.
+	 * @param array $errors Array of error messages to output.
 	 */
 	function output_inline_error($errors)
 	{
@@ -350,8 +354,8 @@ function output_inline_error($errors)
 	/**
 	 * Generate the login page.
 	 *
-	 * @param string The any message to output on the page if there is one.
-	 * @param string The class name of the message (defaults to success)
+	 * @param string $message The any message to output on the page if there is one.
+	 * @param string $class The class name of the message (defaults to success)
 	 */
 	function show_login($message="", $class="success")
 	{
@@ -611,8 +615,8 @@ function show_lockedout()
 	/**
 	 * Generate the lockout unlock page
 	 *
-	 * @param string The any message to output on the page if there is one.
-	 * @param string The class name of the message (defaults to success)
+	 * @param string $message The any message to output on the page if there is one.
+	 * @param string $class The class name of the message (defaults to success)
 	 */
 	function show_lockout_unlock($message="", $class="success")
 	{
@@ -691,11 +695,11 @@ function show_lockout_unlock($message="", $class="success")
 	/**
 	 * Add an item to the primary navigation menu.
 	 *
-	 * @param string The title of the menu item.
-	 * @param string The ID of the menu item. This should correspond with the module the menu will run.
-	 * @param string The link to follow when the menu item is clicked.
-	 * @param int The display order of the menu item. Lower display order means closer to start of the menu.
-	 * @param array Array of sub menu items if there are any.
+	 * @param string $title The title of the menu item.
+	 * @param string $id The ID of the menu item. This should correspond with the module the menu will run.
+	 * @param string $link The link to follow when the menu item is clicked.
+	 * @param int $order The display order of the menu item. Lower display order means closer to start of the menu.
+	 * @param array $submenu Array of sub menu items if there are any.
 	 */
 	function add_menu_item($title, $id, $link, $order=10, $submenu=array())
 	{
@@ -709,6 +713,8 @@ function add_menu_item($title, $id, $link, $order=10, $submenu=array())
 
 	/**
 	 * Build the actual navigation menu.
+	 *
+	 * @return bool|string
 	 */
 	function _build_menu()
 	{
@@ -748,8 +754,8 @@ function _build_menu()
 	/**
 	 * Build a navigation sub menu if we have one.
 	 *
-	 * @param string A title for the sub menu.
-	 * @param array Array of items for the sub menu.
+	 * @param string $title A title for the sub menu.
+	 * @param array $items Array of items for the sub menu.
 	 */
 	function _build_submenu($title, $items)
 	{
@@ -763,6 +769,8 @@ function _build_submenu($title, $items)
 
 	/**
 	 * Switch between two different alternating background colours.
+	 *
+	 * @return string
 	 */
 	function get_alt_bg()
 	{
@@ -782,9 +790,9 @@ function get_alt_bg()
 	/**
 	 * Output a Javascript based tab control on to the page.
 	 *
-	 * @param array Array of tabs in name => title format. Name should correspond to the name of a DIV containing the tab content.
-	 * @param boolean Whether or not to run the event onload or instantly
-	 * @param string The ID to use for the tabs for if you run multiple instances of the tabbing control in one html page
+	 * @param array $tabs Array of tabs in name => title format. Name should correspond to the name of a DIV containing the tab content.
+	 * @param boolean $observe_onload Whether or not to run the event onload or instantly
+	 * @param string $id The ID to use for the tabs for if you run multiple instances of the tabbing control in one html page
 	 */
 	function output_tab_control($tabs=array(), $observe_onload=true, $id="tabs")
 	{
@@ -814,8 +822,8 @@ function output_tab_control($tabs=array(), $observe_onload=true, $id="tabs")
 	/**
 	 * Output a series of primary navigation tabs for swithcing between items within a particular module/action.
 	 *
-	 * @param array Nested array of tabs containing possible keys of align, link_target, link, title.
-	 * @param string The name of the active tab. Corresponds with the key of each tab item.
+	 * @param array $tabs Nested array of tabs containing possible keys of align, link_target, link, title.
+	 * @param string $active The name of the active tab. Corresponds with the key of each tab item.
 	 */
 	function output_nav_tabs($tabs=array(), $active='')
 	{
@@ -859,9 +867,9 @@ function output_nav_tabs($tabs=array(), $active='')
 	/**
 	 * Output a page asking if a user wishes to continue performing a specific action.
 	 *
-	 * @param string The URL to be forwarded to.
-	 * @param string The confirmation message to output.
-	 * @param string The title to use in the output header
+	 * @param string $url The URL to be forwarded to.
+	 * @param string $message The confirmation message to output.
+	 * @param string $title The title to use in the output header
 	 */
 	function output_confirm_action($url, $message="", $title="")
 	{
@@ -899,8 +907,9 @@ function output_confirm_action($url, $message="", $title="")
 	/**
 	 * Build a clickable MyCode editor for the Admin CP.
 	 *
-	 * @param string The ID of the textarea to bind the editor to.
-	 * @param string The language string for the editor.
+	 * @param string $bind The ID of the textarea to bind the editor to.
+	 * @param string $editor_language The language string for the editor.
+	 * @param bool $smilies Whether or not smilies should be included
 	 * @return string The build MyCode editor Javascript.
 	 */
 	function build_codebuttons_editor($bind, $editor_language, $smilies)
@@ -1080,7 +1089,7 @@ function build_codebuttons_editor($bind, $editor_language, $smilies)
 class DefaultSidebarItem
 {
 	/**
-	 * @var The title of the side bar block.
+	 * @var string The title of the side bar block.
 	 */
 	private $_title;
 
@@ -1092,7 +1101,7 @@ class DefaultSidebarItem
 	/**
 	 * Constructor. Set the title of the side bar block.
 	 *
-	 * @param string The title of the side bar block.
+	 * @param string $title The title of the side bar block.
 	 */
 	function __construct($title="")
 	{
@@ -1102,8 +1111,8 @@ function __construct($title="")
 	/**
 	 * Add menus item to the side bar block.
 	 *
-	 * @param array Array of menu items to add. Each menu item should be a nested array of id, link and title.
-	 * @param string The ID of the active menu item if there is one.
+	 * @param array $items Array of menu items to add. Each menu item should be a nested array of id, link and title.
+	 * @param string $active The ID of the active menu item if there is one.
 	 */
 	function add_menu_items($items, $active)
 	{
@@ -1131,7 +1140,7 @@ function add_menu_items($items, $active)
 	/**
 	 * Sets custom html to the contents variable
 	 *
-	 * @param string The custom html to set
+	 * @param string $html The custom html to set
 	 */
 	function set_contents($html)
 	{
@@ -1140,6 +1149,8 @@ function set_contents($html)
 
 	/**
 	 * Fetch the HTML markup for the side bar box.
+	 *
+	 * @return string
 	 */
 	function get_markup()
 	{
@@ -1177,8 +1188,8 @@ class DefaultPopupMenu
 	/**
 	 * Initialise a new popup menu.
 	 *
-	 * @var string The ID of the popup menu.
-	 * @var string The title of the popup menu.
+	 * @var string $id The ID of the popup menu.
+	 * @var string $title The title of the popup menu.
 	 */
 	function __construct($id, $title='')
 	{
@@ -1189,9 +1200,9 @@ function __construct($id, $title='')
 	/**
 	 * Add an item to the popup menu.
 	 *
-	 * @param string The title of this item.
-	 * @param string The page this item should link to.
-	 * @param string The onclick event handler if we have one.
+	 * @param string $text The title of this item.
+	 * @param string $link The page this item should link to.
+	 * @param string $onclick The onclick event handler if we have one.
 	 */
 	function add_item($text, $link, $onclick='')
 	{

admin/inc/class_table.php

@@ -31,8 +31,8 @@ class DefaultTable
 	/**
 	 * Construct an individual cell for this table.
 	 *
-	 * @param string The HTML content for this cell.
-	 * @param array Array of extra information about this cell (class, id, colspan, rowspan, width)
+	 * @param string $data The HTML content for this cell.
+	 * @param array $extra Array of extra information about this cell (class, id, colspan, rowspan, width)
 	 */
 	function construct_cell($data, $extra=array())
 	{
@@ -42,7 +42,7 @@ function construct_cell($data, $extra=array())
 	/**
 	 * Construct a row from the earlier defined constructed cells for the table.
 	 *
-	 * @param array Array of extra information about this row (class, id)
+	 * @param array $extra Array of extra information about this row (class, id)
 	 */
 	function construct_row($extra = array())
 	{
@@ -111,8 +111,8 @@ function construct_row($extra = array())
 	/**
 	 * return the cells of a row for the table based row.
 	 *
-	 * @param string The id of the row you want to give it.
-	 * @param boolean Whether or not to return or echo the resultant contents.
+	 * @param string $row_id The id of the row you want to give it.
+	 * @param boolean $return Whether or not to return or echo the resultant contents.
 	 * @return string The output of the row cells (optional).
 	 */
 	function output_row_cells($row_id, $return=false)
@@ -142,8 +142,8 @@ function num_rows()
 	/**
 	 * Construct a header cell for this table.
 	 *
-	 * @param string The HTML content for this header cell.
-	 * @param array Array of extra information for this header cell (class, style, colspan, width)
+	 * @param string $data The HTML content for this header cell.
+	 * @param array $extra Array of extra information for this header cell (class, style, colspan, width)
 	 */
 	function construct_header($data, $extra=array())
 	{
@@ -153,10 +153,10 @@ function construct_header($data, $extra=array())
 	/**
 	 * Output this table to the browser.
 	 *
-	 * @param string The heading for this table.
-	 * @param int The border width for this table.
-	 * @param string The class for this table.
-	 * @param boolean Whether or not to return or echo the resultant contents.
+	 * @param string $heading The heading for this table.
+	 * @param int $border The border width for this table.
+	 * @param string $class The class for this table.
+	 * @param boolean $return Whether or not to return or echo the resultant contents.
 	 * @return string The output of the row cells (optional).
 	 */
 	function output($heading="", $border=1, $class="general", $return=false)
@@ -174,10 +174,10 @@ function output($heading="", $border=1, $class="general", $return=false)
 	/**
 	 * Fetch the built HTML for this table.
 	 *
-	 * @param string The heading for this table.
-	 * @param int The border width for this table.
-	 * @param string The class for this table.
-	 * @param string The id for this table.
+	 * @param string $heading The heading for this table.
+	 * @param int $border The border width for this table.
+	 * @param string $class The class for this table.
+	 * @param string $table_id The id for this table.
 	 * @return string The built HTML.
 	 */
 	function construct_html($heading="", $border=1, $class=null, $table_id="")