💡 PHPDoc for \DBObject::DBInsert methods hierarchy (and some more, too O:) )

application/cmdbabstract.class.inc.php

@@ -3690,6 +3690,9 @@ EOF
 		return $aErrors;
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	public function DBInsertNoReload()
 	{
 		$res = parent::DBInsertNoReload();
@@ -3707,6 +3710,7 @@ EOF
 	}
 
 	/**
+	 * @inheritdoc
 	 * Attaches InlineImages to the current object
 	 */
 	protected function OnObjectKeyReady()
@@ -3831,6 +3835,12 @@ EOF
 		$this->bAllowWrite = $bAllow;
 	}
 
+	/**
+	 * @inheritdoc
+	 * @throws \ArchivedObjectException
+	 * @throws \CoreException
+	 * @throws \OQLException
+	 */
 	public function DoCheckToWrite()
 	{
 		parent::DoCheckToWrite();

core/cmdbobject.class.inc.php

@@ -188,6 +188,16 @@ abstract class CMDBObject extends DBObject
 		self::$m_oCurrChange->DBInsert();
 	}
 
+	/**
+	 * @inheritdoc
+	 * @throws \ArchivedObjectException
+	 * @throws \CoreCannotSaveObjectException
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \CoreWarning
+	 * @throws \MySQLException
+	 * @throws \OQLException
+	 */
 	protected function RecordObjCreation()
 	{
 		// Delete any existing change tracking about the current object (IDs can be reused due to InnoDb bug; see TRAC #886)
@@ -206,6 +216,7 @@ abstract class CMDBObject extends DBObject
 		MetaModel::PurgeData($oFilter);
 
 		parent::RecordObjCreation();
+
 		$oMyChangeOp = MetaModel::NewObject("CMDBChangeOpCreate");
 		$oMyChangeOp->Set("objclass", get_class($this));
 		$oMyChangeOp->Set("objkey", $this->GetKey());
@@ -232,9 +243,17 @@ abstract class CMDBObject extends DBObject
 	}
 
 	/**
-	 * @param $sAttCode
+	 * @param string $sAttCode
 	 * @param $original Original value
 	 * @param $value Current value
+	 *
+	 * @throws \ArchivedObjectException
+	 * @throws \CoreCannotSaveObjectException
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \CoreWarning
+	 * @throws \MySQLException
+	 * @throws \OQLException
 	 */
 	protected function RecordAttChange($sAttCode, $original, $value)
 	{
@@ -438,6 +457,14 @@ abstract class CMDBObject extends DBObject
 	/**
 	 * @param array $aValues
 	 * @param array $aOrigValues
+	 *
+	 * @throws \ArchivedObjectException
+	 * @throws \CoreCannotSaveObjectException
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \CoreWarning
+	 * @throws \MySQLException
+	 * @throws \OQLException
 	 */
 	protected function RecordAttChanges(array $aValues, array $aOrigValues)
 	{

core/dbobject.class.php

@@ -70,11 +70,14 @@ abstract class DBObject implements iDisplay
 {
 	private static $m_aMemoryObjectsByClass = array();
 
-  	private static $m_aBulkInsertItems = array(); // class => array of ('table' => array of (array of <sql_value>))
+	/** @var array class => array of ('table' => array of (array of <sql_value>)) */
-  	private static $m_aBulkInsertCols = array(); // class => array of ('table' => array of <sql_column>)
+	private static $m_aBulkInsertItems = array();
+	/** @var array class => array of ('table' => array of <sql_column>) */
+	private static $m_aBulkInsertCols = array();
   	private static $m_bBulkInsert = false;
 
-	protected $m_bIsInDB = false; // true IIF the object is mapped to a DB record
+	/** @var bool true IIF the object is mapped to a DB record */
+	protected $m_bIsInDB = false;
 	protected $m_iKey = null;
 	private $m_aCurrValues = array();
 	protected $m_aOrigValues = array();
@@ -232,7 +235,9 @@ abstract class DBObject implements iDisplay
 
 	/**
 	 * @param bool $bAllowAllData DEPRECATED: the reload must never fail!
+	 *
 	 * @throws CoreException
+	 * @internal 
 	 */
 	public function Reload($bAllowAllData = false)
 	{
@@ -748,12 +753,24 @@ abstract class DBObject implements iDisplay
 			}
 		}
 	}
-	
+
+	/**
+	 * Overridable callback, called by \DBObject::DoComputeValues
+	 *
+	 * @api
+	 */
 	public function ComputeValues()
 	{
 	}
 
-	// Compute scalar attributes that depend on any other type of attribute
+	/**
+	 * Compute scalar attributes that depend on any other type of attribute
+	 *
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 *
+	 * @internal
+	 */
 	final public function DoComputeValues()
 	{
 		// TODO - use a flag rather than checking the call stack -> this will certainly accelerate things
@@ -1075,7 +1092,9 @@ abstract class DBObject implements iDisplay
 
 	/**
 	 * Gets the name of an object in a safe manner for displaying inside a web page
+	 *
 	 * @return string
+	 * @throws \CoreException
 	 */
 	public function GetName()
 	{
@@ -1087,13 +1106,20 @@ abstract class DBObject implements iDisplay
 	 * since the " < > characters are not escaped and the name may contain some XSS script
 	 * instructions.
 	 * Use this function only for internal computations or for an output to a non-HTML destination
+	 *
 	 * @return string
+	 * @throws \CoreException
 	 */
 	public function GetRawName()
 	{
 		return $this->Get('friendlyname');
 	}
 
+	/**
+	 * @return mixed|string '' if no state attribute, object representing its value otherwise
+	 * @throws \CoreException
+	 * @internal
+	 */
 	public function GetState()
 	{
 		$sStateAttCode = MetaModel::GetStateAttributeCode(get_class($this));
@@ -1276,9 +1302,15 @@ abstract class DBObject implements iDisplay
 	/**
 	 * Returns the set of flags (OPT_ATT_HIDDEN, OPT_ATT_READONLY, OPT_ATT_MANDATORY...)
 	 * for the given attribute for the current state of the object considered as an INITIAL state
+	 *
 	 * @param string $sAttCode The code of the attribute
+	 * @param array $aReasons
+	 *
 	 * @return integer Flags: the binary combination of the flags applicable to this attribute
-	 */	 	  	 	
+	 * @throws \CoreException
+	 *
+	 * @api
+	 */
 	public function GetInitialStateAttributeFlags($sAttCode, &$aReasons = array())
 	{
 		$iFlags = 0;
@@ -1290,17 +1322,18 @@ abstract class DBObject implements iDisplay
 		return $iFlags; // No need to care about the synchro flags since we'll be creating a new object anyway
 	}
 
-	// check if the given (or current) value is suitable for the attribute
-	// return true if successfull
-	// return the error desciption otherwise
 	/**
+	 * Check if the given (or current) value is suitable for the attribute
+	 *
 	 * @param $sAttCode
-	 * @param null $value
+	 * @param boolean|string $value true if successfull, the error desciption otherwise
 	 *
 	 * @return bool|string
 	 * @throws \ArchivedObjectException
 	 * @throws \CoreException
 	 * @throws \OQLException
+	 *
+	 * @internal
 	 */
 	public function CheckValue($sAttCode, $value = null)
 	{
@@ -1431,8 +1464,13 @@ abstract class DBObject implements iDisplay
 		}
 		return true;
 	}
-	
+
-	// check attributes together
+	/**
+	 * check attributes together
+	 *
+	 * @return bool
+	 * @api
+	 */
 	public function CheckConsistency()
 	{
 		return true;
@@ -1558,12 +1596,15 @@ abstract class DBObject implements iDisplay
 	}
 
 	/**
-	 * check integrity rules (before inserting or updating the object)
+	 * Check integrity rules (before inserting or updating the object)
-	 * a displayable error is returned
+	 *
+	 * Errors should be inserted in {@link $m_aCheckIssues} and {@link $m_aCheckWarnings} arrays
 	 *
 	 * @throws \ArchivedObjectException
 	 * @throws \CoreException
 	 * @throws \OQLException
+	 *
+	 * @api
 	 */
 	public function DoCheckToWrite()
 	{
@@ -1628,6 +1669,8 @@ abstract class DBObject implements iDisplay
 	 * @throws \ArchivedObjectException
 	 * @throws \CoreException
 	 * @throws \OQLException
+	 *
+	 * @internal do not overwrite ! Use {@link DoCheckToWrite} instead
 	 */
 	final public function CheckToWrite()
 	{
@@ -1657,6 +1700,10 @@ abstract class DBObject implements iDisplay
 	// check if it is allowed to delete the existing object from the database
 	// a displayable error is returned
 	/**
+	 * check if it is allowed to delete the existing object from the database
+	 *
+	 * a displayable error is added in {@link $m_aDeleteIssues}
+	 *
 	 * @param \DeletionPlan $oDeletionPlan
 	 *
 	 * @throws \CoreException
@@ -1778,10 +1825,14 @@ abstract class DBObject implements iDisplay
 			}
 		}
 		return $aDelta;
-	} 
+	}
 
-	// List the attributes that have been changed
+	/**
-	// Returns an array of attname => currentvalue
+	 * List the attributes that have been changed
+	 *
+	 * @return array attname => currentvalue
+	 * @internal
+	 */
 	public function ListChanges()
 	{
 		if ($this->m_bIsInDB)
@@ -1841,13 +1892,21 @@ abstract class DBObject implements iDisplay
 		return true;
 	}
 
-	// used only by insert
+	/**
+	 * Used only by insert, Meant to be overloaded
+	 *
+	 * @api
+	 */
 	protected function OnObjectKeyReady()
     {
-        // Meant to be overloaded
     }
 
-	// used both by insert/update
+	/**
+	 * used both by insert/update
+	 *
+	 * @throws \CoreException
+	 * @internal
+	 */
 	private function DBWriteLinks()
 	{
 		foreach(MetaModel::ListAttributeDefs(get_class($this)) as $sAttCode => $oAttDef)
@@ -1856,12 +1915,18 @@ abstract class DBObject implements iDisplay
 			if (!array_key_exists($sAttCode, $this->m_aTouchedAtt)) continue;
 			if (array_key_exists($sAttCode, $this->m_aModifiedAtt) && ($this->m_aModifiedAtt[$sAttCode] == false)) continue;
 
+			/** @var \ormLinkSet $oLinkSet */
 			$oLinkSet = $this->m_aCurrValues[$sAttCode];
 			$oLinkSet->DBWrite($this);
 		}
 	}
 
-	// used both by insert/update
+	/**
+	 * Used both by insert/update
+	 *
+	 * @throws \CoreException
+	 * @internal
+	 */
 	private function WriteExternalAttributes()
 	{
 		foreach (MetaModel::ListAttributeDefs(get_class($this)) as $sAttCode => $oAttDef)
@@ -1902,8 +1967,18 @@ abstract class DBObject implements iDisplay
 		self::$m_aBulkInsertItems = array();
 		self::$m_aBulkInsertCols = array();
 		self::$m_bBulkInsert = false;
-	} 
+	}
 
+	/**
+	 * Persists new object in the DB
+	 *
+	 * @param $sTableClass
+	 *
+	 * @return bool|int false if nothing to persist (no change), new key value otherwise
+	 * @throws \CoreException
+	 * @throws \MySQLException
+	 * @internal
+	 */
 	private function DBInsertSingleTable($sTableClass)
 	{
 		$sTable = MetaModel::DBGetTable($sTableClass);
@@ -1986,7 +2061,7 @@ abstract class DBObject implements iDisplay
 	}
 
 	/**
-	 * Insert of record for the new object into the database
+	 * Persists object to new records in the DB
 	 *
 	 * @return int key of the newly created object
 	 * @throws \ArchivedObjectException
@@ -1996,6 +2071,8 @@ abstract class DBObject implements iDisplay
 	 * @throws \CoreWarning
 	 * @throws \MySQLException
 	 * @throws \OQLException
+	 *
+	 * @internal
 	 */
 	public function DBInsertNoReload()
 	{
@@ -2044,6 +2121,7 @@ abstract class DBObject implements iDisplay
 					if (in_array($sState, $oAttDef->GetStates()))
 					{
 						// Start the stop watch and compute the deadlines
+						/** @var \ormStopWatch $oSW */
 						$oSW = $this->Get($sAttCode);
 						$oSW->Start($this, $oAttDef);
 						$oSW->ComputeDeadlines($this, $oAttDef);
@@ -2199,6 +2277,17 @@ abstract class DBObject implements iDisplay
 		}
 	}
 
+	/**
+	 * @return int|null inserted object key
+	 * @throws \ArchivedObjectException
+	 * @throws \CoreCannotSaveObjectException
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \CoreWarning
+	 * @throws \MySQLException
+	 * @throws \OQLException
+	 * @internal
+	 */
 	public function DBInsert()
 	{
 		$this->DBInsertNoReload();
@@ -3014,32 +3103,56 @@ abstract class DBObject implements iDisplay
 		self::$aPortalToURLMaker[$sPortalId] = $sUrlMakerClass;
 	}
 
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function OnInsert()
 	{
 	}
-	
+
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function AfterInsert()
 	{
 	}
 
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function OnUpdate()
 	{
 	}
 
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function AfterUpdate()
 	{
 	}
 
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function OnDelete()
 	{
 	}
 
-	// To be optionaly overloaded
+	/**
+	 * Can be overloaded
+	 *
+	 * @api
+	 */
 	protected function AfterDelete()
 	{
 	}
@@ -3121,8 +3234,10 @@ abstract class DBObject implements iDisplay
 	}
 
 	/**
-	 *  This object has been created/deleted, record that as a change in link sets pointing to this (if any)
+	 * This object has been created/deleted, record that as a change in link sets pointing to this (if any)
-	 */	
+	 *
+	 * @internal
+	 */
 	private function RecordLinkSetListChange($bAdd = true)
 	{
 		foreach(MetaModel::GetTrackForwardExternalKeys(get_class($this)) as $sExtKeyAttCode => $oLinkSet)
@@ -3147,6 +3262,9 @@ abstract class DBObject implements iDisplay
 		}
 	}
 
+	/**
+	 * @internal
+	 */
 	protected function RecordObjCreation()
 	{
 		$this->RecordLinkSetListChange(true);
@@ -3520,6 +3638,15 @@ abstract class DBObject implements iDisplay
 		return $iFlags;
 	}
 
+	/**
+	 * @return bool true if this object is used in a data synchro
+	 * @throws \CoreException
+	 * @throws \CoreUnexpectedValue
+	 * @throws \MySQLException
+	 * @throws \OQLException
+	 * @internal
+	 * @see \SynchroDataSource
+	 */
 	public function InSyncScope()
 	{
 		//