Adamw has submitted this change and it was merged.
Change subject: Improve PHPDoc for TypesafeEnum, ITypesafeEnum
......................................................................
Improve PHPDoc for TypesafeEnum, ITypesafeEnum
Change-Id: I2d1383b28b3a8d95fbb506446f2b5fcf6b4ddc6b
---
M includes/ITypesafeEnum.php
M includes/TypesafeEnum.php
2 files changed, 52 insertions(+), 14 deletions(-)
Approvals:
Adamw: Looks good to me, approved
jenkins-bot: Verified
diff --git a/includes/ITypesafeEnum.php b/includes/ITypesafeEnum.php
index 8069fdc..68d01c3 100644
--- a/includes/ITypesafeEnum.php
+++ b/includes/ITypesafeEnum.php
@@ -4,17 +4,56 @@
/**
* Interface that defines public methods available on a TypesafeEnum.
+ * @see TypesafeEnum
*/
interface ITypesafeEnum {
+
+ /**
+ * Set up the values of the static properties for the enums.
+ * Should only be called once.
+ *
+ * @throws BadFunctionCallException Thrown if this method is called
more than
+ * once or if the static properties already have values
+ */
public static function setUp();
+ /**
+ * Get an array of declared enum values.
+ *
+ * @return ITypesafeEnum[]
+ */
public static function getValues();
+ /**
+ * Check if an enum is declared on the called class. If a string is
sent,
+ * the value is looked up by name.
+ *
+ * @param TypesafeEnum|string $valOrName
+ * @return boolean
+ */
public static function isDeclared( $valOrName );
+ /**
+ * Returns the enum with this name, as declared by the called class, or
null
+ * if the enum doesn't exist.
+ *
+ * @param string $name
+ * @return ITypesafeEnum
+ */
public static function getValueByName( $name );
+ /**
+ * Get the enum's name.
+ *
+ * @return string
+ */
public function getName();
+ /**
+ * Get the enum's fully qualified name, in this format:
+ * Namespace\Classname::$ENUM_NAME
+ *
+ * @return string
+ */
public function getFullyQualifiedName();
}
\ No newline at end of file
diff --git a/includes/TypesafeEnum.php b/includes/TypesafeEnum.php
index d431f90..d26c5a9 100644
--- a/includes/TypesafeEnum.php
+++ b/includes/TypesafeEnum.php
@@ -8,8 +8,9 @@
/**
* To create some typesafe enums, just extend this class, declare some public
- * static properties, then call YourClassName::setUp(). Your subclass should be
- * final.
+ * static properties without setting thier values, then call
+ * YourClass::setUp(). Also, make your subclass final.
+ * @see ITypesafeEnum
*/
abstract class TypesafeEnum implements ITypesafeEnum {
@@ -29,8 +30,7 @@
protected $fullyQualifiedName;
/**
- * Set the values of the static properties that represent the enum.
- * Only needs to be called once.
+ * @see ITypesafeEnum::setUp()
*/
public static function setUp() {
@@ -67,19 +67,14 @@
}
/**
- * Get a list of declared enum values
- *
- * @return array
+ * @see ITypesafeEnum::getValues()
*/
public static function getValues() {
return array_values( self::$metaByClassName[get_called_class()]
);
}
/**
- * Check if an enum is declared on the called class. If a string is
sent,
- * the value is looked up by name.
- *
- * @param TypesafeEnum|string $valOrName
+ * @see ITypesafeEnum::isDeclared()
*/
public static function isDeclared( $valOrName ) {
@@ -94,9 +89,7 @@
}
/**
- * Returns the enum value with this name, or null if it doesn't exist.
- *
- * @param string $name
+ * @see ITypesafeEnum::getValueByName()
*/
public static function getValueByName( $name ) {
@@ -118,10 +111,16 @@
return $this->name;
}
+ /**
+ * @see ITypesafeEnum::getName()
+ */
public function getName() {
return $this->name;
}
+ /**
+ * @see ITypesafeEnum::getFullyQualifiedName()
+ */
public function getFullyQualifiedName() {
return $this->fullyQualifiedName;
}
--
To view, visit https://gerrit.wikimedia.org/r/133177
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I2d1383b28b3a8d95fbb506446f2b5fcf6b4ddc6b
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Campaigns
Gerrit-Branch: wip/editorcampaigns
Gerrit-Owner: AndyRussG <andrew.green...@gmail.com>
Gerrit-Reviewer: Adamw <awi...@wikimedia.org>
Gerrit-Reviewer: jenkins-bot <>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
