Commit bb7c65ef authored by Robert Lyon's avatar Robert Lyon Committed by Gerrit Code Review
Browse files

Making sure function comment matches function (Bug #1396437)



Change-Id: I573e6f354a2077afbaed5a501d2d99106b736e1a
Signed-off-by: Robert Lyon's avatarRobert Lyon <robertl@catalyst.net.nz>
parent dbe457ba
...@@ -85,7 +85,7 @@ class mahara_group_external extends external_api { ...@@ -85,7 +85,7 @@ class mahara_group_external extends external_api {
* Create one or more group * Create one or more group
* *
* @param array $groups An array of groups to create. * @param array $groups An array of groups to create.
* @return array An array of arrays * @return array An array of arrays describing groups
*/ */
public static function create_groups($groups) { public static function create_groups($groups) {
global $USER, $WEBSERVICE_INSTITUTION; global $USER, $WEBSERVICE_INSTITUTION;
...@@ -222,7 +222,7 @@ class mahara_group_external extends external_api { ...@@ -222,7 +222,7 @@ class mahara_group_external extends external_api {
* parameter definition for output of create_groups method * parameter definition for output of create_groups method
* *
* Returns description of method result value * Returns description of method result value
* @return external_description * @return external_multiple_structure
*/ */
public static function create_groups_returns() { public static function create_groups_returns() {
return new external_multiple_structure( return new external_multiple_structure(
...@@ -313,9 +313,6 @@ class mahara_group_external extends external_api { ...@@ -313,9 +313,6 @@ class mahara_group_external extends external_api {
/** /**
* parameter definition for output of delete_groups method * parameter definition for output of delete_groups method
*
* Returns description of method result value
* @return external_description
*/ */
public static function delete_groups_returns() { public static function delete_groups_returns() {
return null; return null;
...@@ -368,9 +365,9 @@ class mahara_group_external extends external_api { ...@@ -368,9 +365,9 @@ class mahara_group_external extends external_api {
} }
/** /**
* update one or more users * update one or more groups
* *
* @param array $users * @param array $groups
*/ */
public static function update_groups($groups) { public static function update_groups($groups) {
global $USER, $WEBSERVICE_INSTITUTION; global $USER, $WEBSERVICE_INSTITUTION;
...@@ -509,9 +506,6 @@ class mahara_group_external extends external_api { ...@@ -509,9 +506,6 @@ class mahara_group_external extends external_api {
/** /**
* parameter definition for output of update_groups method * parameter definition for output of update_groups method
*
* Returns description of method result value
* @return external_description
*/ */
public static function update_groups_returns() { public static function update_groups_returns() {
return null; return null;
...@@ -554,7 +548,7 @@ class mahara_group_external extends external_api { ...@@ -554,7 +548,7 @@ class mahara_group_external extends external_api {
/** /**
* update one or more sets of group membership * update one or more sets of group membership
* *
* @param array $users * @param array $groups
*/ */
public static function update_group_members($groups) { public static function update_group_members($groups) {
global $USER, $WEBSERVICE_INSTITUTION; global $USER, $WEBSERVICE_INSTITUTION;
...@@ -671,9 +665,6 @@ class mahara_group_external extends external_api { ...@@ -671,9 +665,6 @@ class mahara_group_external extends external_api {
/** /**
* parameter definition for output of update_group_members method * parameter definition for output of update_group_members method
*
* Returns description of method result value
* @return external_description
*/ */
public static function update_group_members_returns() { public static function update_group_members_returns() {
return null; return null;
...@@ -789,7 +780,7 @@ class mahara_group_external extends external_api { ...@@ -789,7 +780,7 @@ class mahara_group_external extends external_api {
* parameter definition for output of get_groups_by_id method * parameter definition for output of get_groups_by_id method
* *
* Returns description of method result value * Returns description of method result value
* @return external_description * @return external_multiple_structure
*/ */
public static function get_groups_by_id_returns() { public static function get_groups_by_id_returns() {
$group_types = group_get_grouptypes(); $group_types = group_get_grouptypes();
...@@ -838,7 +829,6 @@ class mahara_group_external extends external_api { ...@@ -838,7 +829,6 @@ class mahara_group_external extends external_api {
/** /**
* Get group information for all groups * Get group information for all groups
* *
* @param array $groupids array of group ids
* @return array An array of arrays describing groups * @return array An array of arrays describing groups
*/ */
public static function get_groups() { public static function get_groups() {
...@@ -849,7 +839,7 @@ class mahara_group_external extends external_api { ...@@ -849,7 +839,7 @@ class mahara_group_external extends external_api {
* parameter definition for output of get_groups method * parameter definition for output of get_groups method
* *
* Returns description of method result value * Returns description of method result value
* @return external_description * @return external_multiple_structure
*/ */
public static function get_groups_returns() { public static function get_groups_returns() {
return self::get_groups_by_id_returns(); return self::get_groups_by_id_returns();
......
...@@ -91,6 +91,7 @@ class mahara_institution_external extends external_api { ...@@ -91,6 +91,7 @@ class mahara_institution_external extends external_api {
/** /**
* Add one or more members to an institution * Add one or more members to an institution
* *
* @param string $institution
* @param array $users * @param array $users
*/ */
public static function add_members($institution, $users) { public static function add_members($institution, $users) {
...@@ -138,9 +139,6 @@ class mahara_institution_external extends external_api { ...@@ -138,9 +139,6 @@ class mahara_institution_external extends external_api {
/** /**
* parameter definition for output of add_members method * parameter definition for output of add_members method
*
* Returns description of method result value
* @return external_description
*/ */
public static function add_members_returns() { public static function add_members_returns() {
return null; return null;
...@@ -171,6 +169,7 @@ class mahara_institution_external extends external_api { ...@@ -171,6 +169,7 @@ class mahara_institution_external extends external_api {
/** /**
* Invite one or more users to an institution * Invite one or more users to an institution
* *
* @param string $institution
* @param array $users * @param array $users
*/ */
public static function invite_members($institution, $users) { public static function invite_members($institution, $users) {
...@@ -219,9 +218,6 @@ class mahara_institution_external extends external_api { ...@@ -219,9 +218,6 @@ class mahara_institution_external extends external_api {
/** /**
* parameter definition for output of invite_members method * parameter definition for output of invite_members method
*
* Returns description of method result value
* @return external_description
*/ */
public static function invite_members_returns() { public static function invite_members_returns() {
return null; return null;
...@@ -252,6 +248,7 @@ class mahara_institution_external extends external_api { ...@@ -252,6 +248,7 @@ class mahara_institution_external extends external_api {
/** /**
* remove one or more users from an institution * remove one or more users from an institution
* *
* @param string $institution
* @param array $users * @param array $users
*/ */
public static function remove_members($institution, $users) { public static function remove_members($institution, $users) {
...@@ -294,9 +291,6 @@ class mahara_institution_external extends external_api { ...@@ -294,9 +291,6 @@ class mahara_institution_external extends external_api {
/** /**
* parameter definition for output of remove_members method * parameter definition for output of remove_members method
*
* Returns description of method result value
* @return external_description
*/ */
public static function remove_members_returns() { public static function remove_members_returns() {
return null; return null;
...@@ -327,6 +321,7 @@ class mahara_institution_external extends external_api { ...@@ -327,6 +321,7 @@ class mahara_institution_external extends external_api {
/** /**
* decline one or more users request for membership to an institution * decline one or more users request for membership to an institution
* *
* @param string $institution
* @param array $users * @param array $users
*/ */
public static function decline_members($institution, $users) { public static function decline_members($institution, $users) {
...@@ -369,9 +364,6 @@ class mahara_institution_external extends external_api { ...@@ -369,9 +364,6 @@ class mahara_institution_external extends external_api {
/** /**
* parameter definition for output of decline_members method * parameter definition for output of decline_members method
*
* Returns description of method result value
* @return external_description
*/ */
public static function decline_members_returns() { public static function decline_members_returns() {
return null; return null;
...@@ -395,15 +387,15 @@ class mahara_institution_external extends external_api { ...@@ -395,15 +387,15 @@ class mahara_institution_external extends external_api {
/** /**
* Get institution members * Get institution members
* *
* @param array $groups An array of groups to create. * @param string $institution
* @return array An array of arrays * @return array An array of arrays describing users
*/ */
public static function get_members($institution) { public static function get_members($institution) {
global $USER, $WEBSERVICE_INSTITUTION; global $USER, $WEBSERVICE_INSTITUTION;
self::check_oauth(); self::check_oauth();
// Do basic automatic PARAM checks on incoming data, using params description // Do basic automatic PARAM checks on incoming data, using params description
$params = self::validate_parameters(self::get_members_parameters(), array('institution'=>$institution)); $params = self::validate_parameters(self::get_members_parameters(), array('institution' => $institution));
if (!$USER->get('admin') && !$USER->is_institutional_admin()) { if (!$USER->get('admin') && !$USER->is_institutional_admin()) {
throw new AccessDeniedException("Institution::get_members | " . get_string('accessdenied', 'auth.webservice')); throw new AccessDeniedException("Institution::get_members | " . get_string('accessdenied', 'auth.webservice'));
} }
...@@ -428,7 +420,7 @@ class mahara_institution_external extends external_api { ...@@ -428,7 +420,7 @@ class mahara_institution_external extends external_api {
* parameter definition for output of get_members method * parameter definition for output of get_members method
* *
* Returns description of method result value * Returns description of method result value
* @return external_description * @return external_multiple_structure
*/ */
public static function get_members_returns() { public static function get_members_returns() {
return new external_multiple_structure( return new external_multiple_structure(
...@@ -450,17 +442,17 @@ class mahara_institution_external extends external_api { ...@@ -450,17 +442,17 @@ class mahara_institution_external extends external_api {
public static function get_requests_parameters() { public static function get_requests_parameters() {
return new external_function_parameters( return new external_function_parameters(
array( array(
'institution' => new external_value(PARAM_TEXT, 'Mahara institution'), 'institution' => new external_value(PARAM_TEXT, 'Mahara institution'),
) )
); );
} }
/** /**
* Get institution requests * Get institution requests
* *
* @param array $groups An array of groups to create. * @param string $institution
* @return array An array of arrays * @return array An array of arrays describing users
*/ */
public static function get_requests($institution) { public static function get_requests($institution) {
global $USER, $WEBSERVICE_INSTITUTION; global $USER, $WEBSERVICE_INSTITUTION;
...@@ -503,7 +495,7 @@ class mahara_institution_external extends external_api { ...@@ -503,7 +495,7 @@ class mahara_institution_external extends external_api {
* parameter definition for output of get_requests method * parameter definition for output of get_requests method
* *
* Returns description of method result value * Returns description of method result value
* @return external_description * @return external_multiple_structure
*/ */
public static function get_requests_returns() { public static function get_requests_returns() {
return new external_multiple_structure( return new external_multiple_structure(
......
...@@ -114,7 +114,7 @@ class mahara_user_external extends external_api { ...@@ -114,7 +114,7 @@ class mahara_user_external extends external_api {
* Create one or more users in the authorised institution * Create one or more users in the authorised institution
* *
* @param array $users An array of users to create. * @param array $users An array of users to create.
* @return array An array of arrays * @return array An array of arrays describing users
*/ */
public static function create_users($users) { public static function create_users($users) {
global $USER, $WEBSERVICE_INSTITUTION, $WEBSERVICE_OAUTH_USER; global $USER, $WEBSERVICE_INSTITUTION, $WEBSERVICE_OAUTH_USER;
...@@ -284,9 +284,6 @@ class mahara_user_external extends external_api { ...@@ -284,9 +284,6 @@ class mahara_user_external extends external_api {
/** /**
* parameter definition for output of delete_users method * parameter definition for output of delete_users method
*
* Returns description of method result value
* @return external_description
*/ */
public static function delete_users_returns() { public static function delete_users_returns() {
return null; return null;
...@@ -424,9 +421,6 @@ class mahara_user_external extends external_api { ...@@ -424,9 +421,6 @@ class mahara_user_external extends external_api {
/** /**
* parameter definition for output of update_users method * parameter definition for output of update_users method
*
* Returns description of method result value
* @return external_description
*/ */
public static function update_users_returns() { public static function update_users_returns() {
return null; return null;
...@@ -661,7 +655,6 @@ class mahara_user_external extends external_api { ...@@ -661,7 +655,6 @@ class mahara_user_external extends external_api {
/** /**
* Get user information for all users * Get user information for all users
* *
* @param array $userids array of user ids
* @return array An array of arrays describing users * @return array An array of arrays describing users
*/ */
public static function get_users() { public static function get_users() {
...@@ -752,7 +745,6 @@ class mahara_user_external extends external_api { ...@@ -752,7 +745,6 @@ class mahara_user_external extends external_api {
/** /**
* Get my user information - the currently connected user * Get my user information - the currently connected user
* *
* @param array $userids array of user ids
* @return array An array of arrays describing users * @return array An array of arrays describing users
*/ */
public static function get_my_user() { public static function get_my_user() {
...@@ -995,9 +987,6 @@ class mahara_user_external extends external_api { ...@@ -995,9 +987,6 @@ class mahara_user_external extends external_api {
/** /**
* parameter definition for output of update_favourites method * parameter definition for output of update_favourites method
*
* Returns description of method result value
* @return external_description
*/ */
public static function update_favourites_returns() { public static function update_favourites_returns() {
return null; return null;
...@@ -1116,6 +1105,7 @@ class mahara_user_external extends external_api { ...@@ -1116,6 +1105,7 @@ class mahara_user_external extends external_api {
* Get all user favourites * Get all user favourites
* *
* @param string $shortname shortname of the favourites * @param string $shortname shortname of the favourites
* @return array An array describing favourites
*/ */
public static function get_all_favourites($shortname) { public static function get_all_favourites($shortname) {
global $WEBSERVICE_INSTITUTION, $WEBSERVICE_OAUTH_USER; global $WEBSERVICE_INSTITUTION, $WEBSERVICE_OAUTH_USER;
......
...@@ -143,6 +143,7 @@ function mahara_external_atom_returns() { ...@@ -143,6 +143,7 @@ function mahara_external_atom_returns() {
* the account must have membership for the selected auth_instance * the account must have membership for the selected auth_instance
* *
* @param object $dbuser * @param object $dbuser
* @return object $auth_instance or null if $dbuser is empty
*/ */
function webservice_validate_user($dbuser) { function webservice_validate_user($dbuser) {
global $SESSION; global $SESSION;
...@@ -204,7 +205,7 @@ function get_ws_subsystems() { ...@@ -204,7 +205,7 @@ function get_ws_subsystems() {
* @throws WebserviceException * @throws WebserviceException
* @return string token * @return string token
*/ */
function webservice_generate_token($tokentype, $serviceorid, $userid, $institution = 'mahara', $validuntil=0, $iprestriction=''){ function webservice_generate_token($tokentype, $serviceorid, $userid, $institution = 'mahara', $validuntil=0, $iprestriction='') {
global $USER; global $USER;
// make sure the token doesn't exist (even if it should be almost impossible with the random generation) // make sure the token doesn't exist (even if it should be almost impossible with the random generation)
$numtries = 0; $numtries = 0;
...@@ -250,7 +251,10 @@ function webservice_generate_token($tokentype, $serviceorid, $userid, $instituti ...@@ -250,7 +251,10 @@ function webservice_generate_token($tokentype, $serviceorid, $userid, $instituti
* It is expected this will be called in the script generating the html page that is embedding the client app and that the * It is expected this will be called in the script generating the html page that is embedding the client app and that the
* returned token will be somehow passed into the client app being embedded in the page. * returned token will be somehow passed into the client app being embedded in the page.
* @param string $servicename name of the web service. Service name as defined in db/services.php * @param string $servicename name of the web service. Service name as defined in db/services.php
* @param int $context context within which the web service can operate. * @param integer $userid
* @param string $institution
* @param integer $validuntil
* @param string $iprestriction
* @return int returns token id. * @return int returns token id.
*/ */
function webservice_create_service_token($servicename, $userid, $institution = 'mahara', $validuntil=0, $iprestriction='') { function webservice_create_service_token($servicename, $userid, $institution = 'mahara', $validuntil=0, $iprestriction='') {
...@@ -823,6 +827,12 @@ abstract class webservice_server implements webservice_server_interface { ...@@ -823,6 +827,12 @@ abstract class webservice_server implements webservice_server_interface {
$USER->reanimate($user->id, $user->authinstance); $USER->reanimate($user->id, $user->authinstance);
} }
/**
* Authenticate by token type
*
* @param $tokentype string tokentype constant
* @return $user object
*/
protected function authenticate_by_token($tokentype) { protected function authenticate_by_token($tokentype) {
global $WEBSERVICE_INSTITUTION; global $WEBSERVICE_INSTITUTION;
...@@ -1301,6 +1311,12 @@ class ' . $classname . ' { ...@@ -1301,6 +1311,12 @@ class ' . $classname . ' {
return $code; return $code;
} }
/**
* Get phpdoc type
*
* @param object $keydesc
* @return string $type
*/
protected function get_phpdoc_type($keydesc) { protected function get_phpdoc_type($keydesc) {
if ($keydesc instanceof external_value) { if ($keydesc instanceof external_value) {
switch($keydesc->type) { switch($keydesc->type) {
...@@ -1327,6 +1343,12 @@ class ' . $classname . ' { ...@@ -1327,6 +1343,12 @@ class ' . $classname . ' {
return $type; return $type;
} }
/**
* generate simple structure class
*
* @param object $structdesc
* @return string
*/
protected function generate_simple_struct_class(external_single_structure $structdesc) { protected function generate_simple_struct_class(external_single_structure $structdesc) {
//only 'object' is supported by SOAP, 'struct' by XML-RPC MDL-23083 //only 'object' is supported by SOAP, 'struct' by XML-RPC MDL-23083
return 'object|struct'; return 'object|struct';
......
...@@ -183,6 +183,7 @@ die; ...@@ -183,6 +183,7 @@ die;
* get the interface definition for the function * get the interface definition for the function
* *
* @param string $functionname * @param string $functionname
* @return array $vars
*/ */
function testclient_get_interface($functionname) { function testclient_get_interface($functionname) {
$fdesc = webservice_function_info($functionname); $fdesc = webservice_function_info($functionname);
...@@ -201,7 +202,7 @@ function testclient_get_interface($functionname) { ...@@ -201,7 +202,7 @@ function testclient_get_interface($functionname) {
/** /**
* Return indented REST param description * Return indented REST param description
* @param object $paramdescription * @param object $paramdescription
* @param string $indentation composed by space only * @param string $paramstring
* @return string the html to diplay * @return string the html to diplay
*/ */
function testclient_parameters($paramdescription, $paramstring) { function testclient_parameters($paramdescription, $paramstring) {
......
...@@ -11,9 +11,6 @@ ...@@ -11,9 +11,6 @@
define('INTERNAL', 1); define('INTERNAL', 1);
define('MENUITEM', 'configextensions/pluginadminwebservices'); define('MENUITEM', 'configextensions/pluginadminwebservices');
// define('MENUITEM', 'webservice/config');
// define('SECTION_PLUGINTYPE', 'core');
// define('SECTION_PLUGINNAME', 'admin');
define('SECTION_PAGE', 'webservice'); define('SECTION_PAGE', 'webservice');
require(dirname(dirname(__FILE__)) . '/init.php'); require(dirname(dirname(__FILE__)) . '/init.php');
define('TITLE', get_string('pluginadmin', 'admin')); define('TITLE', get_string('pluginadmin', 'admin'));
...@@ -129,7 +126,7 @@ function wsdoc_detailed_description_html($params) { ...@@ -129,7 +126,7 @@ function wsdoc_detailed_description_html($params) {
} }
/** /**
* function that starts it all off * xmlrpc function that starts it all off
* *
* @param $paramname * @param $paramname
* @param $paramdescription * @param $paramdescription
...@@ -193,7 +190,7 @@ EOF; ...@@ -193,7 +190,7 @@ EOF;
} }
/** /**
* function that starts it all off * rest function that starts it all off
* *
* @param $paramname * @param $paramname
* @param $paramdescription * @param $paramdescription
...@@ -203,7 +200,7 @@ function wsdoc_rest($paramname, $paramdescription) { ...@@ -203,7 +200,7 @@ function wsdoc_rest($paramname, $paramdescription) {
} }
/** /**
* function that starts it all off * function that displays rest valid response
* *
* @param $paramname * @param $paramname
* @param $paramdescription * @param $paramdescription
...@@ -222,10 +219,7 @@ EOF; ...@@ -222,10 +219,7 @@ EOF;
} }
/** /**
* function that starts it all off * function that displays rest error response
*
* @param $paramname
* @param $paramdescription
*/ */
function wsdoc_rest_exception() { function wsdoc_rest_exception() {
$errormessage = get_string('invalidparameter', 'auth.webservice'); $errormessage = get_string('invalidparameter', 'auth.webservice');
...@@ -242,8 +236,8 @@ EOF; ...@@ -242,8 +236,8 @@ EOF;