📝 Change packages for auto-documentation

application/applicationextension.inc.php

@@ -29,9 +29,9 @@ require_once(APPROOT.'application/newsroomprovider.class.inc.php');
  * You may implement such interfaces in a module file (e.g. main.mymodule.php)
  *
  * @api
+ * @package     LoginExtensibilityAPI
  * @copyright   Copyright (C) 2010-2012 Combodo SARL
  * @license     http://opensource.org/licenses/AGPL-3.0
- * @package     Extensibility
  * @since       2.7.0
  */
 interface iLoginExtension
@@ -39,12 +39,16 @@ interface iLoginExtension
 	/**
 	 * Return the list of supported login modes for this plugin
 	 *
+	 * @api
+	 *
 	 * @return array of supported login modes
 	 */
 	public function ListSupportedLoginModes();
 }
 
 /**
+ * @api
+ * @package     LoginExtensibilityAPI
  * @since 2.7.0
  */
 interface iLoginFSMExtension extends iLoginExtension
@@ -56,6 +60,7 @@ interface iLoginFSMExtension extends iLoginExtension
 	 * if LoginWebPage::LOGIN_FSM_RETURN_OK is returned then the login is OK and terminated
 	 * if LoginWebPage::LOGIN_FSM_RETURN_IGNORE is returned then the FSM will proceed to next plugin or state
 	 *
+	 * @api
 	 * @param string $sLoginState (see LoginWebPage::LOGIN_STATE_...)
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
@@ -65,6 +70,8 @@ interface iLoginFSMExtension extends iLoginExtension
 }
 
 /**
+ * @api
+ * @package     LoginExtensibilityAPI
  * @since 2.7.0
  */
 abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
@@ -111,6 +118,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	/**
 	 * Initialization
 	 *
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -124,6 +132,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	 * Detect login mode explicitly without respecting configured order (legacy mode)
 	 * In most case do nothing here
 	 *
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -140,6 +149,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	 * 1 - display login form
 	 * 2 - read the values posted by the user
 	 *
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -153,6 +163,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	 * Control the validity of the data provided by the user
 	 * Automatic user provisioning can be done here
 	 *
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -163,6 +174,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	}
 
 	/**
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -173,6 +185,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	}
 
 	/**
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -183,6 +196,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	}
 
 	/**
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -193,6 +207,7 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 	}
 
 	/**
+	 * @api
 	 * @param int $iErrorCode (see LoginWebPage::EXIT_CODE_...)
 	 *
 	 * @return int LoginWebPage::LOGIN_FSM_RETURN_ERROR, LoginWebPage::LOGIN_FSM_RETURN_OK or LoginWebPage::LOGIN_FSM_RETURN_IGNORE
@@ -204,22 +219,28 @@ abstract class AbstractLoginFSMExtension implements iLoginFSMExtension
 }
 
 /**
+ * @api
+ * @package     LoginExtensibilityAPI
  * @since 2.7.0
  */
 interface iLogoutExtension extends iLoginExtension
 {
 	/**
 	 * Execute all actions to log out properly
+	 * @api
 	 */
 	public function LogoutAction();
 }
 
 /**
+ * @api
+ * @package     UIExtensibilityAPI
  * @since 2.7.0
  */
 interface iLoginUIExtension extends iLoginExtension
 {
 	/**
+	 * @api
 	 * @return LoginTwigContext
 	 */
 	public function GetTwigContext();
@@ -233,12 +254,14 @@ interface iLoginUIExtension extends iLoginExtension
 interface iPreferencesExtension
 {
 	/**
+	 * @api
 	 * @param \WebPage $oPage
 	 *
 	 */
 	public function DisplayPreferences(WebPage $oPage);
 
 	/**
+	 * @api
 	 * @param \WebPage $oPage
 	 * @param string $sOperation
 	 *
@@ -319,6 +342,7 @@ interface iApplicationUIExtension
 	 * }
 	 * </code>
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being displayed
 	 * @param WebPage $oPage The output context
 	 * @param boolean $bEditMode True if the edition form is being displayed
@@ -332,6 +356,7 @@ interface iApplicationUIExtension
 	 *
 	 * The method is called rigth after all the tabs have been displayed
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being displayed
 	 * @param WebPage $oPage The output context
 	 * @param boolean $bEditMode True if the edition form is being displayed
@@ -346,6 +371,7 @@ interface iApplicationUIExtension
 	 * The method is called after the changes from the standard form have been
 	 * taken into account, and before saving the changes into the database.
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being edited
 	 * @param string $sFormPrefix Prefix given to the HTML form inputs
 	 *
@@ -360,6 +386,7 @@ interface iApplicationUIExtension
 	 * javascript into the edition form, and if that code requires to store temporary data
 	 * (this is the case when a file must be uploaded).
 	 *
+	 * @api
 	 * @param string $sTempId Unique temporary identifier made of session_id and transaction_id. It identifies the object in a unique way.
 	 *
 	 * @return void
@@ -371,6 +398,7 @@ interface iApplicationUIExtension
 	 *
 	 * Sorry, the verb has been reserved. You must implement it, but it is not called as of now.
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being displayed
 	 *
 	 * @return string[] desc
@@ -382,6 +410,7 @@ interface iApplicationUIExtension
 	 *
 	 * Sorry, the verb has been reserved. You must implement it, but it is not called as of now.
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being displayed
 	 *
 	 * @return string Path of the icon, relative to the modules directory.
@@ -401,6 +430,7 @@ interface iApplicationUIExtension
 	 * * HILIGHT_CLASS_OK
 	 * * HILIGHT_CLASS_NONE
 	 *
+	 * @api
 	 * @param DBObject $oObject The object being displayed
 	 *
 	 * @return integer The value representing the mood of the object
@@ -427,6 +457,7 @@ interface iApplicationUIExtension
 	 *
 	 * See also iPopupMenuExtension for greater flexibility
 	 *
+	 * @api
 	 * @param DBObjectSet $oSet A set of persistent objects (DBObject)
 	 *
 	 * @return string[string]
@@ -525,6 +556,7 @@ interface iApplicationObjectExtension
 	 * If the extension returns false, then the framework will perform the usual evaluation.
 	 * Otherwise, the answer is definitively "yes, the object has changed".
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 *
 	 * @return boolean True if something has changed for the target object
@@ -537,6 +569,7 @@ interface iApplicationObjectExtension
 	 * The GUI calls this verb and reports any issue.
 	 * Anyhow, this API can be called in other contexts such as the CSV import tool.
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 *
 	 * @return string[] A list of errors message. An error message is made of one line and it can be displayed to the end-user.
@@ -550,6 +583,7 @@ interface iApplicationObjectExtension
 	 *
 	 * Please not that it is not possible to cascade deletion by this mean: only stopper issues can be handled.
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 *
 	 * @return string[] A list of errors message. An error message is made of one line and it can be displayed to the end-user.
@@ -565,6 +599,7 @@ interface iApplicationObjectExtension
 	 * * {@see DBObject::ListPreviousValuesForUpdatedAttributes()} : list of changed attributes and their values before the change
 	 * * {@see DBObject::Get()} : for a given attribute the new value that was persisted
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information
 	 *     once for all the changes made within the current page
@@ -580,6 +615,7 @@ interface iApplicationObjectExtension
 	 *
 	 * The method is called right <b>after</b> the object has been written to the database.
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information
 	 *     once for all the changes made within the current page
@@ -593,6 +629,7 @@ interface iApplicationObjectExtension
 	 *
 	 * The method is called right <b>before</b> the object will be deleted from the database.
 	 *
+	 * @api
 	 * @param \cmdbAbstractObject $oObject The target object
 	 * @param CMDBChange|null $oChange A change context. Since 2.0 it is fine to ignore it, as the framework does maintain this information
 	 *     once for all the changes made within the current page
@@ -675,18 +712,21 @@ interface iPopupMenuExtension
 	 * Insert an item into the Actions menu of a list
 	 *
 	 * $param is a DBObjectSet containing the list of objects
+	 * @api
 	 */
 	const MENU_OBJLIST_ACTIONS = 1;
 	/**
 	 * Insert an item into the Toolkit menu of a list
 	 *
 	 * $param is a DBObjectSet containing the list of objects
+	 * @api
 	 */
 	const MENU_OBJLIST_TOOLKIT = 2;
 	/**
 	 * Insert an item into the Actions menu on an object details page
 	 *
 	 * $param is a DBObject instance: the object currently displayed
+	 * @api
 	 */
 	const MENU_OBJDETAILS_ACTIONS = 3;
 	/**
@@ -696,12 +736,14 @@ interface iPopupMenuExtension
 	 * is being displayed.
 	 *
 	 * $param is a Dashboard instance: the dashboard currently displayed
+	 * @api
 	 */
 	const MENU_DASHBOARD_ACTIONS = 4;
 	/**
 	 * Insert an item into the User menu (upper right corner)
 	 *
 	 * $param is null
+	 * @api
 	 */
 	const MENU_USER_ACTIONS = 5;
 	/**
@@ -709,6 +751,7 @@ interface iPopupMenuExtension
 	 *
 	 * $param is an array('portal_id' => $sPortalId, 'object' => $oObject) containing the portal id and a DBObject instance (the object on
 	 * the current line)
+	 * @api
 	 */
 	const PORTAL_OBJLISTITEM_ACTIONS = 7;
 	/**
@@ -716,6 +759,7 @@ interface iPopupMenuExtension
 	 *
 	 * $param is an array('portal_id' => $sPortalId, 'object' => $oObject) containing the portal id and a DBObject instance (the object
 	 * currently displayed)
+	 * @api
 	 */
 	const PORTAL_OBJDETAILS_ACTIONS = 8;
 
@@ -753,6 +797,7 @@ interface iPopupMenuExtension
 	 * This method is called by the framework for each menu.
 	 * The items will be inserted in the menu in the order of the returned array.
 	 *
+	 * @api
 	 * @param int $iMenuId The identifier of the type of menu, as listed by the constants MENU_xxx
 	 * @param mixed $param Depends on $iMenuId, see the constants defined above
 	 *
@@ -826,6 +871,7 @@ abstract class ApplicationPopupMenuItem
 	}
 
 	/**
+	 * @api
 	 * @param $aCssClasses
 	 */
 	public function SetCssClasses($aCssClasses)
@@ -836,6 +882,7 @@ abstract class ApplicationPopupMenuItem
 	/**
 	 * Adds a CSS class to the CSS classes that will be put on the menu item
 	 *
+	 * @api
 	 * @param $sCssClass
 	 */
 	public function AddCssClass($sCssClass)
@@ -875,6 +922,7 @@ class URLPopupMenuItem extends ApplicationPopupMenuItem
 	/**
 	 * Constructor
 	 *
+	 * @api
 	 * @param string $sUID The unique identifier of this menu in iTop... make sure you pass something unique enough
 	 * @param string $sLabel The display label of the menu (must be localized)
 	 * @param string $sURL If the menu is an hyperlink, provide the absolute hyperlink here
@@ -959,6 +1007,7 @@ class SeparatorPopupMenuItem extends ApplicationPopupMenuItem
 
 	/**
 	 * Constructor
+	 * @api
 	 */
 	public function __construct()
 	{
@@ -1020,6 +1069,7 @@ interface iPageUIExtension
 	/**
 	 * Add content to the North pane
 	 *
+	 * @api
 	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 *
 	 * @return string The HTML content to add into the page
@@ -1029,6 +1079,7 @@ interface iPageUIExtension
 	/**
 	 * Add content to the South pane
 	 *
+	 * @api
 	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 *
 	 * @return string The HTML content to add into the page
@@ -1038,6 +1089,7 @@ interface iPageUIExtension
 	/**
 	 * Add content to the "admin banner"
 	 *
+	 * @api
 	 * @param iTopWebPage $oPage The page to insert stuff into.
 	 *
 	 * @return string The HTML content to add into the page
@@ -1098,6 +1150,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns an array of CSS file urls
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return array
@@ -1107,6 +1160,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns inline (raw) CSS
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return string
@@ -1116,6 +1170,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns an array of JS file urls
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return array
@@ -1125,6 +1180,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns raw JS code
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return string
@@ -1134,6 +1190,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns raw HTML code to put at the end of the <body> tag
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return string
@@ -1143,6 +1200,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns raw HTML code to put at the end of the #main-wrapper element
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return string
@@ -1152,6 +1210,7 @@ interface iPortalUIExtension
 	/**
 	 * Returns raw HTML code to put at the end of the #topbar and #sidebar elements
 	 *
+	 * @api
 	 * @param \Symfony\Component\DependencyInjection\Container $oContainer
 	 *
 	 * @return string
@@ -1237,6 +1296,7 @@ interface iRestServiceProvider
 	/**
 	 * Enumerate services delivered by this class
 	 *
+	 * @api
 	 * @param string $sVersion The version (e.g. 1.0) supported by the services
 	 *
 	 * @return array An array of hash 'verb' => verb, 'description' => description
@@ -1246,6 +1306,7 @@ interface iRestServiceProvider
 	/**
 	 * Enumerate services delivered by this class
 	 *
+	 * @api
 	 * @param string $sVersion The version (e.g. 1.0) supported by the services
 	 * @param string $sVerb
 	 * @param array $aParams
@@ -1266,62 +1327,83 @@ class RestResult
 {
 	/**
 	 * Result: no issue has been encountered
+	 * @api
 	 */
 	const OK = 0;
 	/**
 	 * Result: missing/wrong credentials or the user does not have enough rights to perform the requested operation
+	 * @api
 	 */
 	const UNAUTHORIZED = 1;
 	/**
 	 * Result: the parameter 'version' is missing
+	 * @api
 	 */
 	const MISSING_VERSION = 2;
 	/**
 	 * Result: the parameter 'json_data' is missing
+	 * @api
 	 */
 	const MISSING_JSON = 3;
 	/**
 	 * Result: the input structure is not a valid JSON string
+	 * @api
 	 */
 	const INVALID_JSON = 4;
 	/**
 	 * Result: the parameter 'auth_user' is missing, authentication aborted
+	 * @api
 	 */
 	const MISSING_AUTH_USER = 5;
 	/**
 	 * Result: the parameter 'auth_pwd' is missing, authentication aborted
+	 * @api
 	 */
 	const MISSING_AUTH_PWD = 6;
 	/**
 	 * Result: no operation is available for the specified version
+	 * @api
 	 */
 	const UNSUPPORTED_VERSION = 10;
 	/**
 	 * Result: the requested operation is not valid for the specified version
+	 * @api
 	 */
 	const UNKNOWN_OPERATION = 11;
 	/**
 	 * Result: the requested operation cannot be performed because it can cause data (integrity) loss
+	 * @api
 	 */
 	const UNSAFE = 12;
 	/**
 	 * Result: the request page number is not valid. It must be an integer greater than 0
+	 * @api
 	 */
 	const INVALID_PAGE = 13;
 	/**
 	 * Result: the operation could not be performed, see the message for troubleshooting
+	 * @api
 	 */
 	const INTERNAL_ERROR = 100;
 
 	/**
 	 * Default constructor - ok!
+	 * @api
 	 */
 	public function __construct()
 	{
 		$this->code = RestResult::OK;
 	}
 
+	/**
+	 * @var int
+	 * @api
+	 */
 	public $code;
+	/**
+	 * @var string
+	 * @api
+	 */
 	public $message;
 }
 
@@ -1478,6 +1560,7 @@ class RestUtils
 	/**
 	 * Read and interpret object search criteria from a Rest/Json structure
 	 *
+	 * @api
 	 * @param string $sClass Name of the class
 	 * @param StdClass $oCriteria Hash of attribute code => value (can be a substructure or a scalar, depending on the nature of the
 	 *     attriute)
@@ -1587,6 +1670,7 @@ class RestUtils
 	/**
 	 * Search objects from a polymorph search specification (Rest/Json)
 	 *
+	 * @api
 	 * @param string $sClass Name of the class
 	 * @param mixed $key Either search criteria (substructure), or an object or an OQL string.
 	 * @param int $iLimit The limit of results to return