[MediaWiki-commits] [Gerrit] Improve PHPDoc for TypesafeEnum, ITypesafeEnum - change (mediawiki...Campaigns)

[AndyRussG (Code Review)]

AndyRussG has uploaded a new change for review.

  https://gerrit.wikimedia.org/r/133177

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(-)


  git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/Campaigns 
refs/changes/77/133177/1

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: newchange
Gerrit-Change-Id: I2d1383b28b3a8d95fbb506446f2b5fcf6b4ddc6b
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/Campaigns
Gerrit-Branch: wip/editorcampaigns
Gerrit-Owner: AndyRussG <andrew.green...@gmail.com>

_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits