REST service PHPDoc & code cleanup

SVN:trunk[5946]

application/applicationextension.inc.php

@@ -122,7 +122,8 @@ interface iApplicationUIExtension
 	 * Sorry, the verb has been reserved. You must implement it, but it is not called as of now.
 	 * 
 	 * @param DBObject $oObject The object being displayed
-	 * @return type desc
+	 *
+	 * @return string[] desc
 	 */	
 	public function EnumUsedAttributes($oObject); // Not yet implemented
 
@@ -441,8 +442,9 @@ abstract class ApplicationPopupMenuItem
 	
 	/**
 	 * Returns the components to create a popup menu item in HTML
-	 * @return Hash A hash array: array('label' => , 'url' => , 'target' => , 'onclick' => )
-	 * @ignore	 	 
+	 *
+	 * @return array A hash array: array('label' => , 'url' => , 'target' => , 'onclick' => )
+	 * @ignore
 	 */
 	abstract public function GetMenuItem();
 
@@ -759,11 +761,15 @@ interface iRestServiceProvider
 	 * @return array An array of hash 'verb' => verb, 'description' => description
 	 */
 	public function ListOperations($sVersion);
+
 	/**
 	 * Enumerate services delivered by this class
+	 *
 	 * @param string $sVersion The version (e.g. 1.0) supported by the services
+	 * @param string $sVerb
+	 * @param array $aParams
+	 *
 	 * @return RestResult The standardized result structure (at least a message)
-	 * @throws Exception in case of internal failure.	 
 	 */
 	public function ExecOperation($sVersion, $sVerb, $aParams);
 }
@@ -824,10 +830,6 @@ class RestResult
 
 	/**
 	 * Default constructor - ok!
-	 * 	 
-	 * @param DBObject $oObject The object being reported
-	 * @param string $sAttCode The attribute code (must be valid)
-	 * @return string A scalar representation of the value
 	 */
 	public function __construct()
 	{
@@ -865,7 +867,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 mixed parameter value if present
 	 * @throws Exception If the parameter is missing
 	 * @api
 	 */
@@ -888,7 +891,8 @@ class RestUtils
 	 * @param StdClass $oData Structured input data.
 	 * @param string $sParamName Name of the parameter to fetch from the input data
 	 * @param mixed $default Default value if the parameter is not found in the input data
-	 * @return void
+	 *
+	 * @return mixed
 	 * @throws Exception
 	 * @api
 	 */
@@ -910,7 +914,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
 	 */
@@ -931,7 +936,8 @@ class RestUtils
 	 * @param string $sClass Name of the class
 	 * @param StdClass $oData Structured input data.
 	 * @param string $sParamName Name of the parameter to fetch from the input data
-	 * @return An array of class => list of attributes (see RestResultWithObjects::AddObject that uses it)
+	 *
+	 * @return array of class => list of attributes (see RestResultWithObjects::AddObject that uses it)
 	 * @throws Exception
 	 * @api
 	 */
@@ -1111,7 +1117,6 @@ class RestUtils
 		{
 			// OQL
 			$oSearch = DBObjectSearch::FromOQL($key);
-			$oObjectSet = new DBObjectSet($oSearch);
 		}
 		else
 		{

core/userrights.class.inc.php

@@ -1218,8 +1218,9 @@ class UserRights
 	}
 
 	/**
-	 * @param $sProfileName Profile name to search for
-	 * @param $oUser User|null
+	 * @param string $sProfileName Profile name to search for
+	 * @param User|null $oUser
+	 *
 	 * @return bool
 	 */
 	public static function HasProfile($sProfileName, $oUser = null)
@@ -1233,8 +1234,6 @@ class UserRights
 	 * @param Bool Reset admin cache as well
 	 * @return void
 	 */
-	// Reset cached data
-	//
 	public static function FlushPrivileges($bResetAdminCache = false)
 	{
 		if ($bResetAdminCache)
@@ -1255,12 +1254,16 @@ class UserRights
 	}
 
 	static $m_aCacheUsers;
+
 	/**
 	 * Find a user based on its login and its type of authentication
+	 *
 	 * @param string $sLogin Login/identifier of the user
 	 * @param string $sAuthentication Type of authentication used: internal|external|any
 	 * @param bool $bAllowDisabledUsers Whether or not to retrieve disabled users (status != enabled)
+	 *
 	 * @return User The found user or null
+	 * @throws \OQLException
 	 */
 	protected static function FindUser($sLogin, $sAuthentication = 'any', $bAllowDisabledUsers = false)
 	{

webservices/rest.php

@@ -56,6 +56,8 @@
  *
  * @copyright   Copyright (C) 2010-2013 Combodo SARL
  * @license     http://opensource.org/licenses/AGPL-3.0
+ * @link https://www.itophub.io/wiki/page?id=2_5_0%3Aadvancedtopics%3Arest_json REST service documentation
+ * @example https://www.itophub.io/wiki/page?id=2_5_0%3Aadvancedtopics%3Arest_json_playground
  */
 
 if (!defined('__DIR__')) define('__DIR__', dirname(__FILE__));
@@ -172,6 +174,7 @@ try
 	}
 
 
+	/** @var iRestServiceProvider[] $aProviders */
 	$aProviders = array();
 	foreach(get_declared_classes() as $sPHPClass)
 	{
@@ -219,6 +222,7 @@ try
 		{
 			throw new Exception("Unknown verb '$sOperation' in version '$sVersion'", RestResult::UNKNOWN_OPERATION);
 		}
+		/** @var iRestServiceProvider $oRS */
 		$oRS = $aOpToRestService[$sOperation]['service_provider'];
 		$sProvider = get_class($oRS);