From 6b1fcc138b940ce86f8b76d34585f665588f6aa1 Mon Sep 17 00:00:00 2001 From: Damien Regad Date: Sat, 17 Feb 2024 00:15:32 +0100 Subject: [PATCH] PHPDoc --- api/soap/mc_project_api.php | 247 +++++++++++++++++++++--------------- 1 file changed, 146 insertions(+), 101 deletions(-) diff --git a/api/soap/mc_project_api.php b/api/soap/mc_project_api.php index 0b392b6f65..9fd137476b 100644 --- a/api/soap/mc_project_api.php +++ b/api/soap/mc_project_api.php @@ -28,19 +28,20 @@ /** * Use a standard filter to get issues associated with the specified user. * - * @param string $p_username Logged in user name. - * @param string $p_password Login password. - * @param integer $p_project_id Id of project to filter on, or ALL_PROJECTS. - * @param string $p_filter_type The name of the filter to apply - * "assigned" - target user specified - issues assigned to target user that are not resolved. - * "assigned" - target user 0 - unassigned issues that are not resolved. - * "reported" - target user specified - issues reported by user. - * "reported" - target user 0 - will throw. - * "monitored" - target user specified - issues monitored by user. - * "monitored" - target user 0 - issues not monitored. - * @param object $p_target_user AccountData for target user, can include id, name, or both. - * @param integer $p_page_number The page to return (1 based). - * @param integer $p_per_page Number of issues per page. + * @param string $p_username Logged in user name. + * @param string $p_password Login password. + * @param int $p_project_id Id of project to filter on, or ALL_PROJECTS. + * @param string $p_filter_type The name of the filter to apply + * "assigned" - target user specified - issues assigned to target user that are not resolved. + * "assigned" - target user 0 - unassigned issues that are not resolved. + * "reported" - target user specified - issues reported by user. + * "reported" - target user 0 - will throw. + * "monitored" - target user specified - issues monitored by user. + * "monitored" - target user 0 - issues not monitored. + * @param object $p_target_user AccountData for target user, can include id, name, or both. + * @param int $p_page_number The page to return (1 based). + * @param int $p_per_page Number of issues per page. + * * @return array|RestFault|SoapFault a page of matching issues or error. */ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id, $p_filter_type, $p_target_user, $p_page_number, $p_per_page ) { @@ -107,13 +108,15 @@ function mc_project_get_issues_for_user( $p_username, $p_password, $p_project_id } /** - * Project Get Issues - * @param string $p_username Logged in user name. - * @param string $p_password Login password. - * @param integer $p_project_id Project Id. - * @param integer $p_page_number Page number. - * @param integer $p_per_page Per page. - * @return array + * Project Get Issues. + * + * @param string $p_username Logged in user name. + * @param string $p_password Login password. + * @param int $p_project_id Project Id. + * @param int $p_page_number Page number. + * @param int $p_per_page Per page. + * + * @return array|RestFault|SoapFault */ function mc_project_get_issues( $p_username, $p_password, $p_project_id, $p_page_number, $p_per_page ) { global $g_project_override; @@ -158,7 +161,9 @@ function mc_project_get_issues( $p_username, $p_password, $p_project_id, $p_page * * @param string $p_username The name of the user trying to access the project list. * @param string $p_password The password of the user. - * @return array suitable to be converted into a ProjectDataArray + * + * @return array|RestFault|SoapFault Array suitable to be converted into a ProjectDataArray + * @throws ClientException */ function mc_projects_get_user_accessible( $p_username, $p_password ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -194,10 +199,11 @@ function mc_projects_get_user_accessible( $p_username, $p_password ) { /** * Get all categories of a project. * - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @return array An array of category names + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * + * @return array|RestFault|SoapFault An array of category names */ function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -225,12 +231,14 @@ function mc_project_get_categories( $p_username, $p_password, $p_project_id ) { } /** - * Add a new category to a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the new category to add. - * @return integer id of the new category + * Add a new category to a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project for which to add the category. + * @param string $p_category_name The name of the new category to add. + * + * @return int|RestFault|SoapFault Id of the new category */ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_category_name ) { global $g_project_override; @@ -253,12 +261,14 @@ function mc_project_add_category( $p_username, $p_password, $p_project_id, $p_ca } /** - * Delete a category of a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the category to delete. - * @return boolean returns true or false depending on the success of the delete action + * Delete a category of a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * @param string $p_category_name The name of the category to delete. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. */ function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $p_category_name ) { global $g_project_override; @@ -294,14 +304,16 @@ function mc_project_delete_category ( $p_username, $p_password, $p_project_id, $ } /** - * Update a category of a project - * @param string $p_username The name of the user trying to access the categories. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the categories for. - * @param string $p_category_name The name of the category to rename. - * @param string $p_category_name_new The new name of the category to rename. - * @param integer $p_assigned_to User ID that category is assigned to. - * @return boolean returns true or false depending on the success of the update action + * Update a category of a project. + * + * @param string $p_username The name of the user trying to access the categories. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the categories for. + * @param string $p_category_name The name of the category to rename. + * @param string $p_category_name_new The new name of the category to rename. + * @param int $p_assigned_to User ID that category is assigned to. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the update action */ function mc_project_rename_category_by_name( $p_username, $p_password, $p_project_id, $p_category_name, $p_category_name_new, $p_assigned_to ) { global $g_project_override; @@ -335,10 +347,11 @@ function mc_project_rename_category_by_name( $p_username, $p_password, $p_projec /** * Get all versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -368,10 +381,11 @@ function mc_project_get_versions( $p_username, $p_password, $p_project_id ) { /** * Get all released versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_released_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -402,10 +416,11 @@ function mc_project_get_released_versions( $p_username, $p_password, $p_project_ /** * Get all unreleased (a.k.a. future) versions of a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the versions for. - * @return array representing a ProjectVersionDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the versions for. + * + * @return array|RestFault|SoapFault Array representing a ProjectVersionDataArray structure. */ function mc_project_get_unreleased_versions( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -439,8 +454,11 @@ function mc_project_get_unreleased_versions( $p_username, $p_password, $p_projec * * @param string $p_username The name of the user trying to add the issue. * @param string $p_password The password of the user. - * @param stdClass $p_version A ProjectVersionData structure containing information about the new version. - * @return integer The id of the created version. + * @param stdClass $p_version A ProjectVersionData structure containing + * information about the new version. + * + * @return int|RestFault|SoapFault The id of the created version. + * @throws ClientException */ function mc_project_version_add( $p_username, $p_password, stdClass $p_version ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -481,9 +499,12 @@ function mc_project_version_add( $p_username, $p_password, stdClass $p_version ) * * @param string $p_username The name of the user trying to update the issue. * @param string $p_password The password of the user. - * @param integer $p_version_id A version's id. - * @param stdClass $p_version A ProjectVersionData structure containing information about the new version. - * @return boolean returns true or false depending on the success of the update action + * @param int $p_version_id A version's id. + * @param stdClass $p_version A ProjectVersionData structure containing + * information about the new version. + * + * @return bool|RestFault|SoapFault returns true or false depending on the success of the update action. + * @throws ClientException */ function mc_project_version_update( $p_username, $p_password, $p_version_id, stdClass $p_version ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -544,10 +565,12 @@ function mc_project_version_update( $p_username, $p_password, $p_version_id, std /** * Delete a version. * - * @param string $p_username The name of the user trying to delete the version. - * @param string $p_password The password of the user. - * @param integer $p_version_id A version's id. - * @return boolean returns true or false depending on the success of the delete action + * @param string $p_username The name of the user trying to delete the version. + * @param string $p_password The password of the user. + * @param int $p_version_id A version's id. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. + * @throws ClientException */ function mc_project_version_delete( $p_username, $p_password, $p_version_id ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -588,7 +611,8 @@ function mc_project_version_delete( $p_username, $p_password, $p_version_id ) { * * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the custom fields for. + * @param int $p_project_id The id of the project to retrieve the custom fields for. + * * @return array|RestFault|SoapFault representing a CustomFieldDefinitionDataArray structure. */ function mc_project_get_custom_fields( $p_username, $p_password, $p_project_id ) { @@ -608,10 +632,11 @@ function mc_project_get_custom_fields( $p_username, $p_password, $p_project_id ) /** * Validate custom fields before creating/updating issues. * - * @param integer $p_project_id The project id. - * @param array $p_custom_fields The custom fields, may be not set. - * @return bool|SoapFault|RestFault true or error. + * @param int $p_project_id The project id. + * @param array $p_custom_fields The custom fields (by reference). + * May be unset; if so, will be set to null. * + * @return bool true or error. * @throws ClientException */ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) { @@ -710,7 +735,8 @@ function mci_project_custom_fields_validate( $p_project_id, &$p_custom_fields ) /** * Get the custom fields that belong to the specified project. * - * @param integer $p_project_id The id of the project to retrieve the custom fields for. + * @param int $p_project_id The id of the project to retrieve the custom fields for. + * * @return array|RestFault|SoapFault representing a CustomFieldDefinitionDataArray structure. */ function mci_project_get_custom_fields( $p_project_id ) { @@ -785,6 +811,7 @@ function mci_project_get_custom_fields( $p_project_id ) { * Get the custom field type name given its type id. * * @param int $p_type_id The custom field type id. + * * @return string The type name or id if an unknown type. */ function mci_custom_field_type_name( $p_type_id ) { @@ -816,7 +843,9 @@ function mci_custom_field_type_name( $p_type_id ) { /** * Get list of versions for a project. + * * @param int $p_project_id The project id + * * @return array The project versions. */ function mci_project_versions( $p_project_id ) { @@ -845,6 +874,7 @@ function mci_project_versions( $p_project_id ) { * Get projects for the specified project. * * @param int $p_project_id The project id + * * @return array The array of categories with their info. */ function mci_project_categories( $p_project_id ) { @@ -876,10 +906,11 @@ function mci_project_categories( $p_project_id ) { /** * Get the attachments that belong to the specified project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @return array representing a ProjectAttachmentDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * + * @return array|RestFault|SoapFault Array representing a ProjectAttachmentDataArray structure. */ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -968,11 +999,13 @@ function mc_project_get_attachments( $p_username, $p_password, $p_project_id ) { } /** - * Get the list of subprojects for a given project - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @return array + * Get the list of subprojects for a given project. + * + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * + * @return array|RestFault|SoapFault */ function mc_project_get_all_subprojects( $p_username, $p_password, $p_project_id ) { global $g_project_override; @@ -999,7 +1032,8 @@ function mc_project_get_all_subprojects( $p_username, $p_password, $p_project_id /** * Get a project definition. * - * @param integer $p_project_id The id of the project to retrieve. + * @param int $p_project_id The id of the project to retrieve. + * * @return array an array containing the id and the name of the project. */ function mci_project_as_array_by_id( $p_project_id ) { @@ -1015,7 +1049,8 @@ function mci_project_as_array_by_id( $p_project_id ) { * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. * @param string $p_project_name The name of the project to retrieve. - * @return int The id of the project with the given name, 0 if there is no such project. + * + * @return int|RestFault|SoapFault The id of the project with the given name, 0 if there is no such project. */ function mc_project_get_id_from_name( $p_username, $p_password, $p_project_name ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1035,7 +1070,9 @@ function mc_project_get_id_from_name( $p_username, $p_password, $p_project_name * @param string $p_username The name of the user trying to access the versions. * @param string $p_password The password of the user. * @param stdClass $p_project A new ProjectData structure. - * @return int the new project's project_id + * + * @return int|RestFault|SoapFault The new project's project_id + * @throws ClientException */ function mc_project_add( $p_username, $p_password, stdClass $p_project ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1094,9 +1131,11 @@ function mc_project_add( $p_username, $p_password, stdClass $p_project ) { * * @param string $p_username The name of the user. * @param string $p_password The password of the user. - * @param integer $p_project_id A project's identifier. + * @param int $p_project_id A project's identifier. * @param stdClass $p_project A new ProjectData structure. - * @return boolean returns true or false depending on the success of the update action + * + * @return bool|RestFault|SoapFault True or false depending on the success of the update action. + * @throws ClientException */ function mc_project_update( $p_username, $p_password, $p_project_id, stdClass $p_project ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1152,10 +1191,12 @@ function mc_project_update( $p_username, $p_password, $p_project_id, stdClass $p /** * Delete a project. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id A project's identifier. - * @return boolean returns true or false depending on the success of the delete action + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id A project's identifier. + * + * @return bool|RestFault|SoapFault True or false depending on the success of the delete action. + * @throws ClientException */ function mc_project_delete( $p_username, $p_password, $p_project_id ) { $t_user_id = mci_check_login( $p_username, $p_password ); @@ -1176,13 +1217,15 @@ function mc_project_delete( $p_username, $p_password, $p_project_id ) { } /** - * Get Issue Headers - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the attachments for. - * @param integer $p_page_number Page number. - * @param integer $p_per_page Per page. - * @return mixed + * Get Issue Headers. + * + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the attachments for. + * @param int $p_page_number Page number. + * @param int $p_per_page Per page. + * + * @return array|RestFault|SoapFault */ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, $p_page_number, $p_per_page ) { global $g_project_override; @@ -1223,11 +1266,13 @@ function mc_project_get_issue_headers( $p_username, $p_password, $p_project_id, /** * Get appropriate users assigned to a project by access level. * - * @param string $p_username The name of the user trying to access the versions. - * @param string $p_password The password of the user. - * @param integer $p_project_id The id of the project to retrieve the users for. - * @param integer $p_access Minimum access level. - * @return array representing a ProjectAttachmentDataArray structure. + * @param string $p_username The name of the user trying to access the versions. + * @param string $p_password The password of the user. + * @param int $p_project_id The id of the project to retrieve the users for. + * @param int $p_access Minimum access level. + * + * @return array|RestFault|SoapFault Array representing a ProjectAttachmentDataArray structure. + * @throws ClientException */ function mc_project_get_users( $p_username, $p_password, $p_project_id, $p_access ) { global $g_project_override;