From: Matthias Schmidt Date: Sat, 30 Jul 2016 12:35:13 +0000 (+0200) Subject: Improve documentation of `null` as return type (WIP) X-Git-Tag: 3.0.0_Beta_1~883 X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=bea46aa18eaef31fb0f973541ae9d7291fecaaaf;p=GitHub%2FWoltLab%2FWCF.git Improve documentation of `null` as return type (WIP) --- diff --git a/wcfsetup/install/files/lib/data/IStorableObject.class.php b/wcfsetup/install/files/lib/data/IStorableObject.class.php index cf2674bf54..940f9bec33 100644 --- a/wcfsetup/install/files/lib/data/IStorableObject.class.php +++ b/wcfsetup/install/files/lib/data/IStorableObject.class.php @@ -11,7 +11,8 @@ namespace wcf\data; */ interface IStorableObject { /** - * Returns the value of a object data variable with the given name. + * Returns the value of a object data variable with the given name or `null` if no + * such data variable exists. * * @param string $name * @return mixed diff --git a/wcfsetup/install/files/lib/data/ITraversableObject.class.php b/wcfsetup/install/files/lib/data/ITraversableObject.class.php index bcd038eaaa..def958a335 100644 --- a/wcfsetup/install/files/lib/data/ITraversableObject.class.php +++ b/wcfsetup/install/files/lib/data/ITraversableObject.class.php @@ -19,10 +19,10 @@ interface ITraversableObject extends \SeekableIterator { /** * Searches a specific object by object id and setting internal iterator - * pointer to found item. Returns null if object id is not found. + * pointer to found item. Returns `null` if object id is not found. * * @param integer $objectID - * @return \wcf\data\DatabaseObject + * @return DatabaseObject|null */ public function search($objectID); } diff --git a/wcfsetup/install/files/lib/data/article/content/ArticleContent.class.php b/wcfsetup/install/files/lib/data/article/content/ArticleContent.class.php index 042e3d671a..36aec40dbc 100644 --- a/wcfsetup/install/files/lib/data/article/content/ArticleContent.class.php +++ b/wcfsetup/install/files/lib/data/article/content/ArticleContent.class.php @@ -125,9 +125,9 @@ class ArticleContent extends DatabaseObject implements ILinkableObject, IRouteCo } /** - * Returns the language of this article content as language object. + * Returns the language of this article content or `null` if no language has been specified. * - * @return Language|null + * @return Language|null */ public function getLanguage() { if ($this->languageID) { @@ -138,7 +138,7 @@ class ArticleContent extends DatabaseObject implements ILinkableObject, IRouteCo } /** - * Returns a certain article content. + * Returns a certain article content or `null` if it does not exist. * * @param integer $articleID * @param integer $languageID diff --git a/wcfsetup/install/files/lib/data/bbcode/BBCodeCache.class.php b/wcfsetup/install/files/lib/data/bbcode/BBCodeCache.class.php index e8604f3892..187a1c2659 100644 --- a/wcfsetup/install/files/lib/data/bbcode/BBCodeCache.class.php +++ b/wcfsetup/install/files/lib/data/bbcode/BBCodeCache.class.php @@ -43,10 +43,10 @@ class BBCodeCache extends SingletonFactory { } /** - * Returns the BBCode with the given tag or null if no such BBCode exists. + * Returns the BBCode with the given tag or `null` if no such BBCode exists. * * @param string $tag - * @return \wcf\data\bbcode\BBCode + * @return BBCode|null */ public function getBBCodeByTag($tag) { if (isset($this->cachedBBCodes[$tag])) { diff --git a/wcfsetup/install/files/lib/data/box/Box.class.php b/wcfsetup/install/files/lib/data/box/Box.class.php index 14d7aaf660..21864d9fdd 100644 --- a/wcfsetup/install/files/lib/data/box/Box.class.php +++ b/wcfsetup/install/files/lib/data/box/Box.class.php @@ -326,9 +326,9 @@ class Box extends DatabaseObject { } /** - * Returns the image of this box. + * Returns the image of this box or `null` if the box has no image. * - * @return ViewableMedia + * @return ViewableMedia|null */ public function getImage() { if ($this->boxType === 'menu') { diff --git a/wcfsetup/install/files/lib/data/box/content/BoxContent.class.php b/wcfsetup/install/files/lib/data/box/content/BoxContent.class.php index 1280d3c5a9..b3883aed5f 100644 --- a/wcfsetup/install/files/lib/data/box/content/BoxContent.class.php +++ b/wcfsetup/install/files/lib/data/box/content/BoxContent.class.php @@ -39,7 +39,7 @@ class BoxContent extends DatabaseObject { protected $image; /** - * Returns a certain box content. + * Returns a certain box content or `null` if it does not exist. * * @param integer $boxID * @param integer $languageID diff --git a/wcfsetup/install/files/lib/data/category/AbstractDecoratedCategory.class.php b/wcfsetup/install/files/lib/data/category/AbstractDecoratedCategory.class.php index 906e13bc3e..a00b5644dd 100644 --- a/wcfsetup/install/files/lib/data/category/AbstractDecoratedCategory.class.php +++ b/wcfsetup/install/files/lib/data/category/AbstractDecoratedCategory.class.php @@ -97,11 +97,11 @@ abstract class AbstractDecoratedCategory extends DatabaseObjectDecorator { } /** - * Returns the decorated category with the given id or null if no such + * Returns the decorated category with the given id or `null` if no such * category exists. * * @param integer $categoryID - * @return AbstractDecoratedCategory + * @return AbstractDecoratedCategory|null */ public static function getCategory($categoryID) { $category = CategoryHandler::getInstance()->getCategory($categoryID); diff --git a/wcfsetup/install/files/lib/data/like/object/ILikeObject.class.php b/wcfsetup/install/files/lib/data/like/object/ILikeObject.class.php index 10cca0afaf..254b0745fc 100644 --- a/wcfsetup/install/files/lib/data/like/object/ILikeObject.class.php +++ b/wcfsetup/install/files/lib/data/like/object/ILikeObject.class.php @@ -64,9 +64,9 @@ interface ILikeObject extends IDatabaseObjectProcessor, ITitledObject { public function sendNotification(Like $like); /** - * Returns the language id of this object or its parent. + * Returns the language id of this object or its parent or `null` if no explicit language is set. * - * @return integer + * @return integer|null */ public function getLanguageID(); } diff --git a/wcfsetup/install/files/lib/system/acl/ACLHandler.class.php b/wcfsetup/install/files/lib/system/acl/ACLHandler.class.php index 3054ca4c6e..03aa93bb49 100644 --- a/wcfsetup/install/files/lib/system/acl/ACLHandler.class.php +++ b/wcfsetup/install/files/lib/system/acl/ACLHandler.class.php @@ -136,11 +136,12 @@ class ACLHandler extends SingletonFactory { } /** - * Returns the acl option category with the given object type id and name. + * Returns the acl option category with the given object type id and name + * or `null` if no such category exists. * * @param integer $objectTypeID * @param string $categoryName - * @return \wcf\data\acl\option\category\ACLOptionCategory + * @return ACLOptionCategory|null */ public function getCategory($objectTypeID, $categoryName) { if (isset($this->categories[$objectTypeID][$categoryName])) { diff --git a/wcfsetup/install/files/lib/system/application/ApplicationHandler.class.php b/wcfsetup/install/files/lib/system/application/ApplicationHandler.class.php index d142688187..df03621198 100644 --- a/wcfsetup/install/files/lib/system/application/ApplicationHandler.class.php +++ b/wcfsetup/install/files/lib/system/application/ApplicationHandler.class.php @@ -38,10 +38,11 @@ class ApplicationHandler extends SingletonFactory { /** * Returns an application based upon it's abbreviation. Will return the - * primary application if $abbreviation equals to 'wcf' + * primary application if the abbreviation is `wcf` or `null` if no such + * application exists. * * @param string $abbreviation package abbreviation, e.g. `wbb` for `com.woltlab.wbb` - * @return Application + * @return Application|null */ public function getApplication($abbreviation) { if (isset($this->cache['abbreviation'][$abbreviation])) { @@ -56,10 +57,11 @@ class ApplicationHandler extends SingletonFactory { } /** - * Returns an application by package id. + * Returns an application delivered by the package with the given id or `null` + * if no such application exists. * - * @param integer $packageID package id - * @return Application application object + * @param integer $packageID package id + * @return Application|null application object * @since 3.0 */ public function getApplicationByID($packageID) { @@ -132,10 +134,10 @@ class ApplicationHandler extends SingletonFactory { } /** - * Returns abbreviation for a given package id or null if application is unknown. + * Returns abbreviation for a given package id or `null` if application is unknown. * * @param integer $packageID unique package id - * @return string + * @return string|null */ public function getAbbreviation($packageID) { foreach ($this->cache['abbreviation'] as $abbreviation => $applicationID) { diff --git a/wcfsetup/install/files/lib/system/attachment/IAttachmentObjectType.class.php b/wcfsetup/install/files/lib/system/attachment/IAttachmentObjectType.class.php index bb50dba802..c2b77e3dec 100644 --- a/wcfsetup/install/files/lib/system/attachment/IAttachmentObjectType.class.php +++ b/wcfsetup/install/files/lib/system/attachment/IAttachmentObjectType.class.php @@ -1,6 +1,7 @@ categories[$categoryID])) { @@ -103,7 +103,7 @@ class CategoryHandler extends SingletonFactory { } /** - * Returns the category object type with the given id or null if no such object type exists. + * Returns the category object type with the given id or `null` if no such object type exists. * * @param integer $objectTypeID * @return ObjectType|null @@ -117,7 +117,7 @@ class CategoryHandler extends SingletonFactory { } /** - * Returns the category object type with the given name or null if no such object type exists. + * Returns the category object type with the given name or `null` if no such object type exists. * * @param string $objectType * @return ObjectType|null diff --git a/wcfsetup/install/files/lib/system/category/ICategoryType.class.php b/wcfsetup/install/files/lib/system/category/ICategoryType.class.php index 7ba45d49b8..237e1563d4 100644 --- a/wcfsetup/install/files/lib/system/category/ICategoryType.class.php +++ b/wcfsetup/install/files/lib/system/category/ICategoryType.class.php @@ -74,11 +74,10 @@ interface ICategoryType { /** * Returns the name of the object type of the definition with the given - * name for categories of this type. If categories of this type are no - * object of the relevant type, null is returned. + * name for categories of this type or `null` if no such object type exists. * * @param string $definitionName - * @return string + * @return string|null */ public function getObjectTypeName($definitionName); diff --git a/wcfsetup/install/files/lib/system/clipboard/ClipboardHandler.class.php b/wcfsetup/install/files/lib/system/clipboard/ClipboardHandler.class.php index dea634ab49..e9d419f948 100644 --- a/wcfsetup/install/files/lib/system/clipboard/ClipboardHandler.class.php +++ b/wcfsetup/install/files/lib/system/clipboard/ClipboardHandler.class.php @@ -1,5 +1,6 @@ cache['objectTypeNames'][$typeName])) { @@ -149,10 +151,11 @@ class ClipboardHandler extends SingletonFactory { } /** - * Returns a type by object type id. + * Returns the clipboard object type with the given id or `null` if no such + * clipboard object type exists. * - * @param integer $objectTypeID - * @return \wcf\data\object\type\ObjectType + * @param integer $objectTypeID + * @return ObjectType|null */ public function getObjectType($objectTypeID) { if (isset($this->cache['objectTypes'][$objectTypeID])) { @@ -163,10 +166,13 @@ class ClipboardHandler extends SingletonFactory { } /** - * Returns object type by object type name. + * Returns the id of the clipboard object type with the given name or `null` if no such + * clipboard object type exists. + * + * TODO: The name of this method does not reflect its return type and appears not to be used. * * @param string $objectType - * @return integer + * @return integer|null */ public function getObjectTypeByName($objectType) { foreach ($this->cache['objectTypes'] as $objectTypeID => $objectTypeObj) { @@ -290,11 +296,11 @@ class ClipboardHandler extends SingletonFactory { } /** - * Returns items for clipboard editor. + * Returns the data of the items for clipboard editor or `null` if no items are marked. * * @param string|string[] $page * @param integer $pageObjectID - * @return mixed[][] + * @return array|null * @throws SystemException */ public function getEditorItems($page, $pageObjectID) { diff --git a/wcfsetup/install/files/lib/system/clipboard/action/IClipboardAction.class.php b/wcfsetup/install/files/lib/system/clipboard/action/IClipboardAction.class.php index 8b6c74d144..d8732bb4da 100644 --- a/wcfsetup/install/files/lib/system/clipboard/action/IClipboardAction.class.php +++ b/wcfsetup/install/files/lib/system/clipboard/action/IClipboardAction.class.php @@ -2,6 +2,7 @@ namespace wcf\system\clipboard\action; use wcf\data\clipboard\action\ClipboardAction; use wcf\data\DatabaseObject; +use wcf\system\clipboard\ClipboardEditorItem; /** * Basic interface for all clipboard editor actions. @@ -20,12 +21,12 @@ interface IClipboardAction { public function getTypeName(); /** - * Returns editor item for the clipboard action with the given name or null + * Returns the editor item for the clipboard action with the given name or `null` * if the action is not applicable to the given objects. * - * @param DatabaseObject[] $objects - * @param \wcf\data\clipboard\action\ClipboardAction $action - * @return \wcf\system\clipboard\ClipboardEditorItem + * @param DatabaseObject[] $objects + * @param ClipboardAction $action + * @return ClipboardEditorItem|null */ public function execute(array $objects, ClipboardAction $action); diff --git a/wcfsetup/install/files/lib/system/comment/CommentHandler.class.php b/wcfsetup/install/files/lib/system/comment/CommentHandler.class.php index 32098632da..b0817373f6 100644 --- a/wcfsetup/install/files/lib/system/comment/CommentHandler.class.php +++ b/wcfsetup/install/files/lib/system/comment/CommentHandler.class.php @@ -49,10 +49,11 @@ class CommentHandler extends SingletonFactory { } /** - * Returns the object type id for a given object type. + * Returns the id of the comment object type with the given name or `null` if no + * such object type exists. * * @param string $objectType - * @return integer + * @return integer|null */ public function getObjectTypeID($objectType) { if (isset($this->cache['objectTypeIDs'][$objectType])) { @@ -63,10 +64,11 @@ class CommentHandler extends SingletonFactory { } /** - * Returns the object type for a given object type id. + * Returns the comment object type with the given name or `null` if no such + * object type exists. * * @param integer $objectTypeID - * @return ObjectType + * @return ObjectType|null */ public function getObjectType($objectTypeID) { if (isset($this->cache['objectTypes'][$objectTypeID])) { diff --git a/wcfsetup/install/files/lib/system/condition/AbstractIntegerCondition.class.php b/wcfsetup/install/files/lib/system/condition/AbstractIntegerCondition.class.php index 2e610731ae..37c5254db2 100644 --- a/wcfsetup/install/files/lib/system/condition/AbstractIntegerCondition.class.php +++ b/wcfsetup/install/files/lib/system/condition/AbstractIntegerCondition.class.php @@ -133,10 +133,10 @@ HTML; } /** - * Returns the maximum value the property can have or null if there is no + * Returns the maximum value the property can have or `null` if there is no * such maximum. * - * @return integer + * @return integer|null */ protected function getMaxValue() { if ($this->getDecoratedObject()->maxvalue !== null) { @@ -169,10 +169,10 @@ HTML; } /** - * Returns the minimum value the property can have or null if there is no + * Returns the minimum value the property can have or `null` if there is no * such minimum. * - * @return integer + * @return integer|null */ protected function getMinValue() { if ($this->getDecoratedObject()->minvalue !== null) { diff --git a/wcfsetup/install/files/lib/system/option/ISearchableConditionUserOption.class.php b/wcfsetup/install/files/lib/system/option/ISearchableConditionUserOption.class.php index 50df569eb9..d7112bcc93 100644 --- a/wcfsetup/install/files/lib/system/option/ISearchableConditionUserOption.class.php +++ b/wcfsetup/install/files/lib/system/option/ISearchableConditionUserOption.class.php @@ -35,7 +35,7 @@ interface ISearchableConditionUserOption extends ISearchableUserOption { public function checkUser(User $user, Option $option, $value); /** - * Returns the data of the condition or null if the option should be ignored. + * Returns the data of the condition or `null` if the option should be ignored. * * @param Option $option * @param mixed $newValue diff --git a/wcfsetup/install/files/lib/system/package/plugin/AbstractXMLPackageInstallationPlugin.class.php b/wcfsetup/install/files/lib/system/package/plugin/AbstractXMLPackageInstallationPlugin.class.php index 9576e7bf38..5cb3a7eb87 100644 --- a/wcfsetup/install/files/lib/system/package/plugin/AbstractXMLPackageInstallationPlugin.class.php +++ b/wcfsetup/install/files/lib/system/package/plugin/AbstractXMLPackageInstallationPlugin.class.php @@ -295,10 +295,11 @@ abstract class AbstractXMLPackageInstallationPlugin extends AbstractPackageInsta protected function validateImport(array $data) { } /** - * Find an existing item for updating, should return sql query. + * Returns an array with a sql query and its parameters to find an existing item for updating + * or `null` if updates are not supported. * - * @param array $data - * @return array + * @param array $data + * @return array|null */ abstract protected function findExistingItem(array $data); diff --git a/wcfsetup/install/files/lib/system/package/plugin/IPackageInstallationPlugin.class.php b/wcfsetup/install/files/lib/system/package/plugin/IPackageInstallationPlugin.class.php index 409db32ed6..2d91907cf3 100644 --- a/wcfsetup/install/files/lib/system/package/plugin/IPackageInstallationPlugin.class.php +++ b/wcfsetup/install/files/lib/system/package/plugin/IPackageInstallationPlugin.class.php @@ -35,8 +35,8 @@ interface IPackageInstallationPlugin { public function uninstall(); /** - * Returns the default file name containing the instructions. If no default - * file name is supported, null is returned. + * Returns the default file name containing the instructions or `null` if no default + * file name is supported. * * @return string * @since 3.0 @@ -47,8 +47,8 @@ interface IPackageInstallationPlugin { * Validates if the passed instruction is valid for this package installation plugin. If anything is * wrong with it, this method should return false. * - * @param \wcf\system\package\PackageArchive $packageArchive - * @param string $instruction + * @param PackageArchive $packageArchive + * @param string $instruction * @return boolean */ public static function isValid(PackageArchive $packageArchive, $instruction); diff --git a/wcfsetup/install/files/lib/system/request/ControllerMap.class.php b/wcfsetup/install/files/lib/system/request/ControllerMap.class.php index eba3ddcd20..c083072f11 100644 --- a/wcfsetup/install/files/lib/system/request/ControllerMap.class.php +++ b/wcfsetup/install/files/lib/system/request/ControllerMap.class.php @@ -298,14 +298,14 @@ class ControllerMap extends SingletonFactory { } /** - * Returns the class data for the active request or null if for the given - * configuration no proper class exist. + * Returns the class data for the active request or `null` if no proper class exists + * for the given configuration. * * @param string $application application identifier * @param string $controller controller name * @param boolean $isAcpRequest true if this is an ACP request * @param string $pageType page type, e.g. 'form' or 'action' - * @return string[] className, controller and pageType + * @return string[]|null className, controller and pageType */ protected function getClassData($application, $controller, $isAcpRequest, $pageType) { $className = $application . '\\' . ($isAcpRequest ? 'acp\\' : '') . $pageType . '\\' . $controller . ucfirst($pageType); diff --git a/wcfsetup/install/files/lib/system/search/ArticleSearch.class.php b/wcfsetup/install/files/lib/system/search/ArticleSearch.class.php index b6ec332b98..f70b4ee48e 100644 --- a/wcfsetup/install/files/lib/system/search/ArticleSearch.class.php +++ b/wcfsetup/install/files/lib/system/search/ArticleSearch.class.php @@ -51,7 +51,10 @@ class ArticleSearch extends AbstractSearchableObjectType { * @inheritDoc */ public function getObject($objectID) { - if (isset($this->messageCache[$objectID])) return $this->messageCache[$objectID]; + if (isset($this->messageCache[$objectID])) { + return $this->messageCache[$objectID]; + } + return null; } diff --git a/wcfsetup/install/files/lib/system/search/ISearchableObjectType.class.php b/wcfsetup/install/files/lib/system/search/ISearchableObjectType.class.php index 8a0a06d009..60c45f47e5 100644 --- a/wcfsetup/install/files/lib/system/search/ISearchableObjectType.class.php +++ b/wcfsetup/install/files/lib/system/search/ISearchableObjectType.class.php @@ -44,10 +44,10 @@ interface ISearchableObjectType { public function getApplication(); /** - * Returns the search conditions of this message type. + * Returns the search conditions of this message type or `null` if no special search conditions are necessary. * * @param IForm $form - * @return PreparedStatementConditionBuilder + * @return PreparedStatementConditionBuilder|null */ public function getConditions(IForm $form = null); diff --git a/wcfsetup/install/files/lib/system/user/authentication/IUserAuthentication.class.php b/wcfsetup/install/files/lib/system/user/authentication/IUserAuthentication.class.php index cb8c18f0a2..aec8646230 100644 --- a/wcfsetup/install/files/lib/system/user/authentication/IUserAuthentication.class.php +++ b/wcfsetup/install/files/lib/system/user/authentication/IUserAuthentication.class.php @@ -14,7 +14,7 @@ interface IUserAuthentication { /** * Returns an unique instance of the authentication class * - * @return \wcf\system\user\authentication\IUserAuthentication + * @return IUserAuthentication */ public static function getInstance(); @@ -28,28 +28,28 @@ interface IUserAuthentication { /** * Stores the user access data for a persistent login. * - * @param \wcf\data\user\User $user - * @param string $username - * @param string $password + * @param User $user + * @param string $username + * @param string $password */ public function storeAccessData(User $user, $username, $password); /** - * Does a manual user login. + * Does a manual user login or `null` if login was unsuccessful. * * @param string $username * @param string $password * @param string $userClassname class name of user class - * @return \wcf\data\user\User + * @return User|null */ public function loginManually($username, $password, $userClassname = User::class); /** - * Does a user login automatically. + * Does a user login automatically or `null` if login was unsuccessful. * * @param boolean $persistent true = persistent login * @param string $userClassname class name of user class - * @return \wcf\data\user\User + * @return User|null */ public function loginAutomatically($persistent = false, $userClassname = User::class); }