Support PHP enumerations

Author: ramsey

.gitignore

@@ -1,5 +1,6 @@
 dist/
 build/
+doc/_build
 test/_build
 *.pyc
 *.egg-info

doc/reference.rst

@@ -50,6 +50,62 @@ Each directive populates the index, and or the namespace index.
    Describe a trait.  Methods beloning to the trait should follow or be nested
    inside this directive.
 
+.. rst:directive:: .. php:enum:: name [ : type ]
+
+   Describes an enum. Cases, methods, and constants belonging to the enum
+   should be inside this directive's body::
+
+        .. php:enum:: Suit
+
+            In playing cards, a suit is one of the categories into which the
+            cards of a deck are divided.
+
+            .. php:case:: Hearts
+
+                Hearts is one of the four suits in playing cards.
+
+            .. php:case:: Diamonds
+
+                Diamonds is one of the four suits in playing cards.
+
+            .. php:case:: Clubs
+
+                Clubs is one of the four suits in playing cards.
+
+            .. php:case:: Spades
+
+                Spades is one of the four suits in playing cards.
+
+            .. php:method:: color() -> string
+
+                Returns "Red" for hearts and diamonds and "black" for clubs
+                and spades.
+
+            .. php:const:: Roses : Hearts
+
+                An alias for :php:case:`Suit::Hearts`.
+
+   You may describe a backed enum by specifying the optional enum type and
+   case values::
+
+        .. php:enum:: Suit : string
+
+            In playing cards, a suit is one of the categories into which the
+            cards of a deck are divided.
+
+            .. php:case:: Hearts : 'H'
+
+            .. php:case:: Diamonds : 'D'
+
+            .. php:case:: Clubs : 'C'
+
+            .. php:case:: Spades : 'S'
+
+.. rst:directive:: .. php:case:: name [ : value ]
+
+   Describes an enum case. If describing a backed enum case, you may also
+   provide the case value. See :rst:dir:`php:enum` for examples.
+
 .. rst:directive:: .. php:class:: name
 
    Describes a class.  Methods, attributes, and constants belonging to the class
@@ -166,3 +222,14 @@ matching directive is found:
 
    Reference a trait. A namespaced name may be used.
 
+.. rst:role:: php:enum
+
+   Reference an enum. A namespaced name may be used::
+
+     :php:enum:`Example\\Suit`
+
+.. rst:role:: php:case
+
+   Reference an enum case. A namespace name may be used::
+
+     :php:case:`Example\\Suit::Hearts`

sphinxcontrib/phpdomain.py

@@ -28,8 +28,9 @@
           ([\w.]*\:\:)?                     # class name(s)
           (\$?\w+)  \s*                     # thing name
           (?: \((.*)\)                      # optional: arguments
-          (?:\s* -> \s* (.*))?              # return annotation
-          )? $                              # and nothing more
+          (?:\s* -> \s* (.*))?)?            # return annotation
+          (?:\s* : \s* (.*))?               # backed enum type / case value
+          $                                 # and nothing more
           ''', re.VERBOSE)
 
 
@@ -46,7 +47,9 @@
   'exception': '',
   'staticmethod': '::',
   'interface': NS,
-  'trait': NS
+  'trait': NS,
+  'enum': NS,
+  'case': '::',
 }
 
 php_separator = re.compile(r"(\w+)?(?:[:]{2})?")
@@ -157,7 +160,7 @@ def handle_signature(self, sig, signode):
         if m is None:
             raise ValueError
 
-        visibility, modifiers, name_prefix, name, arglist, retann = m.groups()
+        visibility, modifiers, name_prefix, name, arglist, retann, enumtype = m.groups()
 
         if not name_prefix:
             name_prefix = ""
@@ -191,7 +194,7 @@ def handle_signature(self, sig, signode):
                 fullname = name_prefix + name
 
             # Currently in a class, but not creating another class,
-            elif classname and not self.objtype in ['class', 'exception', 'interface', 'trait']:
+            elif classname and not self.objtype in ['class', 'exception', 'interface', 'trait', 'enum']:
                 if not self.env.temp_data['php:in_class']:
                     name_prefix = classname + separator
 
@@ -239,12 +242,16 @@ def handle_signature(self, sig, signode):
                 signode += addnodes.desc_parameterlist()
             if retann:
                 signode += addnodes.desc_returns(retann, retann)
+            elif enumtype:
+                signode += addnodes.desc_returns(enumtype, enumtype)
             return fullname, name_prefix
 
         _pseudo_parse_arglist(signode, arglist)
 
         if retann:
             signode += addnodes.desc_returns(retann, retann)
+        elif enumtype:
+            signode += addnodes.desc_returns(enumtype, enumtype)
         return fullname, name_prefix
 
     def get_index_text(self, modname, name):
@@ -341,7 +348,7 @@ def get_index_text(self, modname, name_cls):
 class PhpClasslike(PhpObject):
     """
     Description of a class-like object
-    (classes, exceptions, interfaces, traits).
+    (classes, exceptions, interfaces, traits, enums).
     """
 
     def get_signature_prefix(self, sig):
@@ -360,6 +367,10 @@ def get_index_text(self, modname, name_cls):
             if not modname:
                 return _('%s (trait)') % name_cls[0]
             return _('%s (trait in %s)') % (name_cls[0], modname)
+        elif self.objtype == 'enum':
+            if not modname:
+                return _('%s (enum)') % name_cls[0]
+            return _('%s (enum in %s)') % (name_cls[0], modname)
         elif self.objtype == 'exception':
             return name_cls[0]
         else:
@@ -384,6 +395,8 @@ def get_signature_prefix(self, sig):
             return _('property ')
         if self.objtype == 'staticmethod':
             return _('static ')
+        if self.objtype == 'case':
+            return _('case ')
         return ''
 
     def needs_arglist(self):
@@ -393,7 +406,7 @@ def get_index_text(self, modname, name_cls):
         name, cls = name_cls
         add_modules = self.env.config.add_module_names
 
-        if self.objtype.endswith('method') or self.objtype == 'attr':
+        if self.objtype.endswith('method') or self.objtype == 'attr' or self.objtype == 'case':
             try:
                 clsname, propname = php_rsplit(name)
             except ValueError:
@@ -414,6 +427,13 @@ def get_index_text(self, modname, name_cls):
                 return _('%s (%s\\%s property)') % (propname, modname, clsname)
             else:
                 return _('%s (%s property)') % (propname, clsname)
+        elif self.objtype == 'case':
+            if modname and clsname is None:
+                return _('%s enum case') % (name)
+            elif modname and add_modules:
+                return _('%s (%s\\%s enum case)') % (propname, modname, clsname)
+            else:
+                return _('%s (%s enum case)') % (propname, clsname)
         else:
             return ''
 
@@ -586,6 +606,8 @@ class PhpDomain(Domain):
         'namespace': ObjType(_('namespace'), 'ns', 'obj'),
         'interface': ObjType(_('interface'), 'interface', 'obj'),
         'trait': ObjType(_('trait'), 'trait', 'obj'),
+        'enum': ObjType(_('enum'), 'enum', 'obj'),
+        'case': ObjType(_('case'), 'case', 'obj'),
     }
 
     directives = {
@@ -596,9 +618,11 @@ class PhpDomain(Domain):
         'method': PhpClassmember,
         'staticmethod': PhpClassmember,
         'attr': PhpClassmember,
+        'case': PhpClassmember,
         'exception': PhpClasslike,
         'interface': PhpClasslike,
         'trait': PhpClasslike,
+        'enum': PhpClasslike,
         'namespace': PhpNamespace,
         'currentmodule': PhpCurrentNamespace,
         'currentnamespace': PhpCurrentNamespace,
@@ -616,6 +640,8 @@ class PhpDomain(Domain):
         'obj': PhpXRefRole(),
         'interface': PhpXRefRole(),
         'trait': PhpXRefRole(),
+        'enum': PhpXRefRole(),
+        'case': PhpXRefRole(),
     }
 
     initial_data = {

test/test_doc.rst

@@ -472,3 +472,129 @@ Return Types
 .. php:class:: ReturnedClass
 
     A class to return.
+
+Enums
+=====
+
+Basic Enumerations
+------------------
+
+.. php:namespace:: Example\Basic
+
+.. php:enum:: Suit
+
+    In playing cards, a suit is one of the categories into which the cards of a
+    deck are divided.
+
+    .. php:case:: Hearts
+    .. php:case:: Diamonds
+    .. php:case:: Clubs
+    .. php:case:: Spades
+
+Backed Enumerations
+-------------------
+
+.. php:namespace:: Example\Backed
+
+.. php:enum:: Suit : string
+
+    In playing cards, a suit is one of the categories into which the cards of a
+    deck are divided.
+
+    .. php:case:: Hearts : 'H'
+    .. php:case:: Diamonds : 'D'
+    .. php:case:: Clubs : 'C'
+    .. php:case:: Spades : 'S'
+
+Advanced Enumerations
+---------------------
+
+.. php:namespace:: Example\Advanced
+
+.. php:enum:: Suit : string
+
+    In playing cards, a suit is one of the categories into which the cards of a
+    deck are divided.
+
+    .. php:case:: Hearts : 'H'
+    .. php:case:: Diamonds : 'D'
+    .. php:case:: Clubs : 'C'
+    .. php:case:: Spades : 'S'
+
+    .. php:method:: color() -> string
+
+        Returns "red" for hearts and diamonds, "black" for clubs and spades.
+
+    .. php:staticmethod:: values() -> string[]
+
+        Returns an array of the values of all the cases on this enum.
+
+    .. php:const:: Roses() : Hearts
+
+        An alias for :php:case:`Example\\Advanced\\Suit::Hearts`.
+
+    .. php:const:: Bells : Diamonds
+
+        An alias for :php:case:`Example\\Advanced\\Suit::Diamonds`.
+
+    .. php:const:: Acorns : Clubs
+
+        An alias for :php:case:`Example\\Advanced\\Suit::Clubs`.
+
+    .. php:const:: Shields : Spades
+
+        An alias for :php:case:`Example\\Advanced\\Suit::Spades`.
+
+Enumeration Links
+-----------------
+
+Links to Basic Enumeration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:php:enum:`Example\\Basic\\Suit`
+
+:php:case:`Example\\Basic\\Suit::Hearts`
+
+:php:case:`Example\\Basic\\Suit::Diamonds`
+
+:php:case:`Example\\Basic\\Suit::Clubs`
+
+:php:case:`Example\\Basic\\Suit::Spades`
+
+Links to Backed Enumeration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:php:enum:`Example\\Backed\\Suit`
+
+:php:case:`Example\\Backed\\Suit::Hearts`
+
+:php:case:`Example\\Backed\\Suit::Diamonds`
+
+:php:case:`Example\\Backed\\Suit::Clubs`
+
+:php:case:`Example\\Backed\\Suit::Spades`
+
+Links to Advanced Enumeration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:php:enum:`Example\\Advanced\\Suit`
+
+:php:case:`Example\\Advanced\\Suit::Hearts`
+
+:php:case:`Example\\Advanced\\Suit::Diamonds`
+
+:php:case:`Example\\Advanced\\Suit::Clubs`
+
+:php:case:`Example\\Advanced\\Suit::Spades`
+
+:php:meth:`Example\\Advanced\\Suit::color`
+
+:php:meth:`Example\\Advanced\\Suit::values`
+
+:php:const:`Example\\Advanced\\Suit::Roses`
+
+:php:const:`Example\\Advanced\\Suit::Bells`
+
+:php:const:`Example\\Advanced\\Suit::Acorns`
+
+:php:const:`Example\\Advanced\\Suit::Shields`