From 44f5d71e1bcf5fc49b51867cb1cd9721b1155385 Mon Sep 17 00:00:00 2001
From: Pierre Goiffon <pierre.goiffon@combodo.com>
Date: Mon, 4 Mar 2019 16:00:22 +0100
Subject: [PATCH] :bulb: PHPDoc for REST API

---
 application/applicationextension.inc.php | 6 ++++--
 core/restservices.class.inc.php          | 9 ++++++++-
 webservices/rest.php                     | 6 ++++--
 webservices/webservices.basic.php        | 4 ++--
 4 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/application/applicationextension.inc.php b/application/applicationextension.inc.php
index 0c0ee5b9a..8d8862e92 100644
--- a/application/applicationextension.inc.php
+++ b/application/applicationextension.inc.php
@@ -869,7 +869,8 @@ class RestUtils
 	 * 	 
 	 * @param StdClass $oData Structured input data. Must contain the entry defined by sParamName.
 	 * @param string $sParamName Name of the parameter to fetch from the input data
-	 * @return void
+	 *
+	 * @return string
 	 * @throws Exception If the parameter is missing
 	 * @api
 	 */
@@ -914,7 +915,8 @@ class RestUtils
 	 *
 	 * @param StdClass $oData Structured input data. Must contain the entry defined by sParamName.
 	 * @param string $sParamName Name of the parameter to fetch from the input data
-	 * @return void
+	 *
+	 * @return string
 	 * @throws Exception If the parameter is missing or the class is unknown
 	 * @api
 	 */
diff --git a/core/restservices.class.inc.php b/core/restservices.class.inc.php
index 2ec01292c..37693a24c 100644
--- a/core/restservices.class.inc.php
+++ b/core/restservices.class.inc.php
@@ -299,9 +299,16 @@ class CoreServices implements iRestServiceProvider
 
 	/**
 	 * Enumerate services delivered by this class
+	 *
 	 * @param string $sVersion The version (e.g. 1.0) supported by the services
+	 * @param string $sVerb
+	 * @param $aParams
+	 *
 	 * @return RestResult The standardized result structure (at least a message)
-	 * @throws Exception in case of internal failure.	 
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \SimpleGraphException
+	 * @throws \Exception
 	 */
 	public function ExecOperation($sVersion, $sVerb, $aParams)
 	{
diff --git a/webservices/rest.php b/webservices/rest.php
index 849e5e2a7..af278043f 100644
--- a/webservices/rest.php
+++ b/webservices/rest.php
@@ -81,7 +81,7 @@ class RestResultListOperations extends RestResult
 		$this->operations[] = array(
 			'verb' => $sVerb,
 			'description' => $sDescription,
-			'extension' => $sServiceProviderClass
+			'extension' => $sServiceProviderClass,
 		);
 	}
 }
@@ -94,7 +94,7 @@ if (!function_exists('json_last_error_msg')) {
 			JSON_ERROR_STATE_MISMATCH => 'State mismatch (invalid or malformed JSON)',
 			JSON_ERROR_CTRL_CHAR => 'Control character error, possibly incorrectly encoded',
 			JSON_ERROR_SYNTAX => 'Syntax error',
-			JSON_ERROR_UTF8 => 'Malformed UTF-8 characters, possibly incorrectly encoded'
+			JSON_ERROR_UTF8 => 'Malformed UTF-8 characters, possibly incorrectly encoded',
 		);
 
 		$error = json_last_error();
@@ -172,6 +172,7 @@ try
 	}
 
 
+	/** var iRestServiceProvider[] $aProviders */
 	$aProviders = array();
 	foreach(get_declared_classes() as $sPHPClass)
 	{
@@ -183,6 +184,7 @@ try
 	}
 
 	$aOpToRestService = array(); // verb => $oRestServiceProvider
+	/** @var iRestServiceProvider $oRestSP */
 	foreach ($aProviders as $oRestSP)
 	{
 		$aOperations = $oRestSP->ListOperations($sVersion);
diff --git a/webservices/webservices.basic.php b/webservices/webservices.basic.php
index af469aa9d..54c187825 100644
--- a/webservices/webservices.basic.php
+++ b/webservices/webservices.basic.php
@@ -36,8 +36,8 @@ class BasicServices extends WebServicesBase
 
 	/**
 	 * Get the server version (TODO: get it dynamically, where ?)
-	 *	 
-	 * @return WebServiceResult
+	 *
+	 * @return string WebServiceResult
 	 */
 	static public function GetVersion()
 	{