phpdoc fixes + exceptions

admin/check/check_api.php

@@ -44,11 +44,11 @@ function check_init_error_handler() {
 
 /**
  * Implement Error handler for check framework
- * @param int type
- * @param string error
- * @param string file
- * @param int line
- * @param string context
+ * @param int $p_type type
+ * @param string $p_error error
+ * @param string $p_file file
+ * @param int $p_line line
+ * @param string $p_context context
  */
 function check_error_handler( $p_type, $p_error, $p_file, $p_line, $p_context ) {
 	global $g_errors_raised;
@@ -149,7 +149,7 @@ function check_print_info_row( $p_description, $p_info = null ) {
 
 /**
  * Print Check Test Result
- * @param int BAD|GOOD|WARN
+ * @param int $p_result BAD|GOOD|WARN
  */
 function check_print_test_result( $p_result ) {
 	global $g_alternate_row, $g_failed_test, $g_passed_test_with_warnings;
@@ -170,9 +170,10 @@ function check_print_test_result( $p_result ) {
 
 /**
  * Print Check Test Row
- * @param string description
- * @param bool pass
- * @param string information
+ * @param string $p_description description
+ * @param bool $p_pass pass
+ * @param string $p_info information
+ * @return bool
  */
 function check_print_test_row( $p_description, $p_pass, $p_info = null ) {
 	global $g_alternate_row, $g_show_all;

admin/check/check_integrity_inc.php

@@ -47,7 +47,7 @@
 /**
  * Returns the Git Object hash for given file
  *
- * @param string filename of file contained in git repository
+ * @param string $p_file filename of file contained in git repository
  * @return string
  */
 function create_git_object_hash( $p_file ) {
@@ -60,8 +60,8 @@ function create_git_object_hash( $p_file ) {
 
 /**
  * Get git tag of object hash for given file
- * @param string filename of file contained in git repository
- * @param string object hash
+ * @param string $p_filename filename of file contained in git repository
+ * @param string $p_object_hash object hash
  * @return string
  */
 function get_release_containing_object_hash( $p_filename, $p_object_hash ) {
@@ -102,10 +102,10 @@ function get_commit_containing_object_hash( $p_filename, $p_object_hash ) {
 /**
  * Check File integrity of local files against release
  *
- * @param string directory
- * @param string base directory
- * @param string relative path prefix
- * @param array files to ignore
+ * @param string $p_directory directory
+ * @param string $p_base_directory base directory
+ * @param string $p_relative_path_prefix relative path prefix
+ * @param array $p_ignore_files files to ignore
  * @return null;
  */
 function check_file_integrity_recursive( $p_directory, $p_base_directory, $p_relative_path_prefix = '', $p_ignore_files = array() ) {

admin/db_stats.php

@@ -32,8 +32,8 @@
 /**
  * Output HTML Table Row
  *
- * @param string Row Description
- * @param string Row Value
+ * @param string $p_description Row Description
+ * @param string $p_value Row Value
  */
 function print_info_row( $p_description, $p_value ) {
 	echo '<tr>';
@@ -45,7 +45,7 @@ function print_info_row( $p_description, $p_value ) {
 /**
  * Function to get row count for a given table
  *
- * @param string table name
+ * @param string $p_table table name
  * @return int row count
  */
 function helper_table_row_count( $p_table ) {

admin/index.php

@@ -33,8 +33,8 @@
 /**
  * Print Check result - information only
  *
- * @param string description
- * @param string information
+ * @param string $p_description description
+ * @param string $p_value information
  */
 function print_info_row( $p_description, $p_value ) {
 	echo '<tr>';

admin/move_db2disk.php

@@ -33,22 +33,19 @@
 /**
  * Get File Path prefix
  *
- * @param string file path
+ * @param string $p_file_path file path
  * @return string
  */
-function get_prefix( $file_path ) {
-	if( substr( $file_path, 0, 1 ) == '/' ) {
-
+function get_prefix( $p_file_path ) {
+	if( substr( $p_file_path, 0, 1 ) == '/' ) {
 		# Unix absolute
 		return '';
 	}
-	if( substr( $file_path, 0, 1 ) == '\\' ) {
-
+	if( substr( $p_file_path, 0, 1 ) == '\\' ) {
 		# Windows absolute
 		return '';
 	}
-	if( substr( $file_path, 1, 2 ) == ':\\' ) {
-
+	if( substr( $p_file_path, 1, 2 ) == ':\\' ) {
 		# Windows absolute
 		return '';
 	}
@@ -67,7 +64,7 @@ function get_prefix( $file_path ) {
  * Re-running this is safe because the data
  * is not removed from the database until it is successfully copied.
  *
- * @param string source - either attachment or project
+ * @param string $p_source source - either attachment or project
  * @return null
  */
 function upgrade_move_att2disk( $p_source ) {

admin/test_langs.php

@@ -371,11 +371,11 @@ function checktoken( $file, $base = false ) {
 
 /**
  * Error handler for language file checks
- * @param int type
- * @param string error
- * @param string file
- * @param int line
- * @param string context
+ * @param int $p_type type
+ * @param string $p_error error
+ * @param string $p_file file
+ * @param int $p_line line
+ * @param string $p_context context
  */
 function lang_error_handler( $p_type, $p_error, $p_file, $p_line, $p_context ) {
 	print_error( "error handler thrown: " . $p_type . '<br />' . $p_error . '<br />' . $p_file . '<br />' . $p_line . '<br />' . $p_context );
@@ -384,7 +384,7 @@ function lang_error_handler( $p_type, $p_error, $p_file, $p_line, $p_context ) {
 /**
  * Print Language File error
  *
- * @param string error string
+ * @param string $p_string error string
  */
 function print_error( $p_string ) {
 	echo '<p class="error-msg">ERROR: ', $p_string, '</p>';

bug_actiongroup_add_note_inc.php

@@ -93,7 +93,7 @@ function action_add_note_print_fields() {
 /**
  * Validates the action on the specified bug id.
  *
- * @param int bug id
+ * @param int $p_bug_id bug id
  * @return string|null On failure: the reason why the action could not be validated. On success: null.
  * @throws MantisBT\Exception\Field\EmptyField
  */
@@ -121,7 +121,7 @@ function action_add_note_validate( $p_bug_id ) {
 /**
  * Executes the custom action on the specified bug id.
  *
- * @param $p_bug_id  The bug id to execute the custom action on.
+ * @param int $p_bug_id The bug id to execute the custom action on.
  * @return null Previous validation ensures that this function doesn't fail. Therefore we can always return null to indicate no errors occurred.
  */
 function action_add_note_process( $p_bug_id ) {

bug_actiongroup_update_product_build_inc.php

@@ -63,7 +63,7 @@ function action_update_product_build_print_fields() {
 /**
  * Validates the action on the specified bug id.
  *
- * @param $p_bug_id Bug ID
+ * @param int $p_bug_id Bug ID
  * @return string|null On failure: the reason why the action could not be validated. On success: null.
  */
 function action_update_product_build_validate( $p_bug_id ) {
@@ -83,7 +83,7 @@ function action_update_product_build_validate( $p_bug_id ) {
 /**
  * Executes the custom action on the specified bug id.
  *
- * @param $p_bug_id  The bug id to execute the custom action on.
+ * @param int $p_bug_id The bug id to execute the custom action on.
  * @return null Previous validation ensures that this function doesn't fail. Therefore we can always return null to indicate no errors occurred.
  */
 function action_update_product_build_process( $p_bug_id ) {

bug_actiongroup_update_severity_inc.php

@@ -69,7 +69,7 @@ function action_update_severity_print_fields() {
 /**
  * Validates the action on the specified bug id.
  *
- * @param int bug id
+ * @param int $p_bug_id bug id
  * @return string|null On failure: the reason why the action could not be validated. On success: null.
  */
 function action_update_severity_validate( $p_bug_id ) {
@@ -92,7 +92,7 @@ function action_update_severity_validate( $p_bug_id ) {
 /**
  * Executes the custom action on the specified bug id.
  *
- * @param $p_bug_id  The bug id to execute the custom action on.
+ * @param int $p_bug_id The bug id to execute the custom action on.
  * @return null Previous validation ensures that this function doesn't fail. Therefore we can always return null to indicate no errors occurred.
  */
 function action_update_severity_process( $p_bug_id ) {

bug_monitor_list_view_inc.php

@@ -78,7 +78,7 @@
 			$t_can_delete_others = access_has_bug_level( config_get( 'monitor_delete_others_bug_threshold' ), $f_bug_id );
 	 		for ( $i = 0; $i < $num_users; $i++ ) {
 				echo ($i > 0) ? ', ' : '';
-				echo print_user( $t_users[$i] );
+				print_user( $t_users[$i] );
 				if ( $t_can_delete_others ) {
 					echo ' [<a class="small" href="' . helper_mantis_url( 'bug_monitor_delete.php' ) . '?bug_id=' . $f_bug_id . '&amp;user_id=' . $t_users[$i] . htmlspecialchars(form_security_param( 'bug_monitor_delete' )) . '">' . lang_get( 'delete_link' ) . '</a>]';
 				}

bug_revision_view_page.php

@@ -95,7 +95,7 @@
 /**
  * Show Bug revision
  *
- * @param array Bug Revision Data
+ * @param array $p_revision Bug Revision Data
  * @return null
  */
 function show_revision( $p_revision ) {

bugnote_view_inc.php

@@ -159,7 +159,7 @@
 
 		<span class="bugnote-reporter">
 		<?php
-			echo print_user( $t_bugnote->reporter_id );
+			print_user( $t_bugnote->reporter_id );
 		?>
 		<span class="small access-level"><?php
 			if ( user_exists( $t_bugnote->reporter_id ) ) {

changelog_page.php

@@ -90,7 +90,9 @@ function print_version_header( $p_version_id ) {
 		$t_release_date = '';
 	}
 
-	echo '<br />', $t_release_title, $t_release_date, lang_get( 'word_separator' ), print_bracket_link( 'view_all_set.php?type=1&temporary=y&' . FILTER_PROPERTY_PROJECT_ID . '=' . $t_project_id . '&' . filter_encode_field_and_value( FILTER_PROPERTY_FIXED_IN_VERSION, $t_version_name ), lang_get( 'view_bugs_link' ) ), '<br />';
+	echo '<br />', $t_release_title, $t_release_date, lang_get( 'word_separator' );
+    print_bracket_link( 'view_all_set.php?type=1&temporary=y&' . FILTER_PROPERTY_PROJECT_ID . '=' . $t_project_id . '&' . filter_encode_field_and_value( FILTER_PROPERTY_FIXED_IN_VERSION, $t_version_name ), lang_get( 'view_bugs_link' ) );
+    echo '<br />';
 
 	$t_release_title_without_hyperlinks = $t_project_name . ' - ' . $t_version_name . $t_release_date;
 	echo utf8_str_pad( '', utf8_strlen( $t_release_title_without_hyperlinks ), '=' ), '<br />';

core/authentication_api.php

@@ -565,7 +565,7 @@ function auth_is_cookie_string_unique( $p_cookie_string ) {
  * if no user is logged in and anonymous login is enabled, returns cookie for anonymous user
  * otherwise returns '' (an empty string)
  *
- * @param boolean auto-login anonymous user
+ * @param boolean $p_login_anonymous auto-login anonymous user
  * @return string current user login cookie string
  * @access public
  */
@@ -609,7 +609,7 @@ function auth_get_current_user_cookie( $p_login_anonymous=true ) {
 
 /**
  * Set authentication tokens for secure session.
- * @param integer User ID
+ * @param integer $p_user_id User ID
  * @access public
  */
 function auth_set_tokens( $p_user_id ) {
@@ -655,8 +655,8 @@ function auth_reauthenticate() {
 
 /**
  * Generate the intermediate authentication page.
- * @param integer User ID
- * @param string Username
+ * @param integer $p_user_id User ID
+ * @param string $p_username Username
  * @return bool
  * @access public
  */
@@ -795,7 +795,7 @@ function auth_http_prompt() {
 	header( 'WWW-Authenticate: Basic realm="' . lang_get( 'http_auth_realm' ) . '"' );
 	header( 'status: 401 Unauthorized' );
 
-	echo '<p class="center error-msg">' . error_string( ERROR_ACCESS_DENIED ) . '</p>';
+	echo '<p class="center error-msg">' . lang_get( 'access_denied' ) . '</p>';
 	print_bracket_link( 'main_page.php', lang_get( 'proceed' ) );
 
 	exit;

core/bug_api.php

@@ -812,8 +812,8 @@ function bug_close( $p_bug, $p_bugnote_text = '', $p_bugnote_private = false, $p
  * @param int $p_handler_id handler id
  * @param bool $p_bugnote_private private bugnote
  * @param string $p_time_tracking time tracking
- * @return bool (alawys true)
  * @access public
+ * @throws MantisBT\Exception\Issue\IssueDuplicateSelf
  */
 function bug_resolve( $p_bug, $p_resolution, $p_fixed_in_version = '', $p_bugnote_text = '', $p_duplicate_id = null, $p_handler_id = null, $p_bugnote_private = false, $p_time_tracking = '0:00' ) {
 	$c_resolution = (int) $p_resolution;
@@ -826,7 +826,7 @@ function bug_resolve( $p_bug, $p_resolution, $p_fixed_in_version = '', $p_bugnot
 	$t_duplicate = !is_blank( $p_duplicate_id ) && ( $p_duplicate_id != 0 );
 	if( $t_duplicate ) {
 		if( $p_bug->id == $p_duplicate_id ) {
-			throw new MantisBT\Exception\Bug_Duplicate_Self();
+			throw new MantisBT\Exception\Issue\IssueDuplicateSelf();
 
 			# never returns
 		}
@@ -885,8 +885,6 @@ function bug_resolve( $p_bug, $p_resolution, $p_fixed_in_version = '', $p_bugnot
 	email_relationship_child_resolved( $p_bug->id );
 
 	twitter_issue_resolved( $p_bug->id );
-
-	return true;
 }
 
 /**

core/bug_revision_api.php

@@ -99,22 +99,23 @@ function bug_revision_exists( $p_revision_id ) {
  * Get a row of data for a given revision ID.
  * @param int $p_revision_id Revision ID
  * @return array Revision data row
+ * @throws MantisBT\Exception\Issue\Revision\RevisionNotFound
  */
 function bug_revision_get( $p_revision_id ) {
 	$t_query = 'SELECT * FROM {bug_revision} WHERE id=%d';
 	$t_result = db_query( $t_query, array( $p_revision_id ) );
 
 	$t_row = db_fetch_array( $t_result );
 	if ( !$t_row ) {
-		throw new MantisBT\Exception\Bug_Revision_Not_Found();
+		throw new MantisBT\Exception\Issue\Revision\RevisionNotFound();
 	}
 
 	return $t_row;
 }
 
 /**
  * Get the name of the type of a bug revision.
- * @param int Revision type ID (see constant_inc.php for possible values)
+ * @param int $p_revision_type_id Revision type ID (see constant_inc.php for possible values)
  * @return string Name of the type of the bug revision
  */
 function bug_revision_get_type_name( $p_revision_type_id ) {
@@ -291,6 +292,7 @@ function bug_revision_list( $p_bug_id, $p_type=REV_ANY, $p_bugnote_id=0 ) {
  * given revision ID.
  * @param int $p_rev_id Revision ID
  * @return array|null Array of Revision rows
+ * @throws MantisBT\Exception\Issue\Revision\RevisionNotFound
  */
 function bug_revision_like( $p_rev_id ) {
 	$t_query = 'SELECT bug_id, bugnote_id, type FROM {bug_revision} WHERE id=%d';
@@ -299,7 +301,7 @@ function bug_revision_like( $p_rev_id ) {
 	$t_row = db_fetch_array( $t_result );
 
 	if ( !$t_row ) {
-		throw new MantisBT\Exception\Bug_Revision_Not_Found();
+		throw new MantisBT\Exception\Issue\Revision\RevisionNotFound();
 	}
 
 	$t_bug_id = $t_row['bug_id'];