Fix rendering of throws, allowing it to co-exist with return intents (#103)

Fixes an issue where `throws` and a return intent would break parsing of
chapel signatures. This was because the parser was capturing `throws`
and treating it like a return intent, so it didn't know what to do with
the actual return intent.

To implement this, I actually had to fix several things
- return intents and return types where parsed together, complicating
the addition of throws. I split them apart
- just using regex, the pattern `const throws` would get treated as a
single intent, which is not correct. This required me to add a special
function to fixup the regex match.

Fixes the issue described in
chapel-lang/chapel#23776, once this fix
propagates to Chapel main.

[Reviewed by @lydia-duncan]

Author: jabraham17

doc-test/classes.rst

@@ -110,6 +110,8 @@ Chapel classes
 
         Some method that does something.
 
+.. class:: ClassA:ClassB,ClassC
+
 Python classes
 --------------
 

doc-test/functions.rst

@@ -140,6 +140,12 @@ Chapel Functions
     :throw PermissionError: when the message is not for you
 
 
+.. function:: proc throwsWithIntent() const ref throws
+
+.. function:: proc throwsWithIntent2() const throws
+
+.. function:: proc throwsWithIntentAndReturn() ref : int throws
+
 Other stuff...
 --------------
 

sphinxcontrib/chapeldomain/__init__.py

@@ -56,14 +56,70 @@
            (?:[+*/!~%<>=&^|\-:]+)                  #  or operator name
           )  \s*
           (?:\((.*?)\))?                           # opt: arguments
-          (\s+(?:const\s)? (?:\w+?)|               #  or return intent
-           \s* : \s* (?:[^:]+?)|                   #  or return type
-           \s+(?:const\s)? \w+\s* : \s* (?:[^:]+?) #  or return intent and type
+          (\s+(?:const\s)? (?:\w+?)                # opt: return intent
+          )?
+          (\s*:\s*(?:[^:]+?)                       # opt: return type
+          )?
+          (\s+throws                               # opt: throws
           )?
           (\s+where\s+.*                           # Where clause
           )?
           $""", re.VERBOSE)
 
+
+def match_chpl_sig_pattern(sig: str):
+    """
+    Match a Chapel signature against the regex pattern defined in
+    chpl_sig_pattern. chpl_sig_pattern cannot be used directly because we need
+    to fix some things up
+
+    For example, `const throws` will be treated by the regex as a return
+    intent, when really it is a `const` return intent and a `throws`. This
+    function splits them apart
+
+    Additionally, this function cleans up the whitespace on the return type
+    (and removes ':'!), return intent, and any captured throws to make testing
+    more consistent.
+    """
+    sig_match = chpl_sig_pattern.match(sig)
+    if not sig_match:
+        return None
+    (
+        func_prefix,
+        name_prefix,
+        name,
+        arglist,
+        return_intent,
+        return_type,
+        throws,
+        where_clause,
+    ) = sig_match.groups()
+
+    if return_type:
+        return_type = return_type.strip().removeprefix(':').lstrip()
+    if return_intent:
+        return_intent = return_intent.strip()
+    if throws:
+        throws = throws.strip()
+
+    if return_intent and "throws" in return_intent:
+        return_intent = return_intent.replace("throws", "").strip()
+        if not return_intent:
+            return_intent = None
+        throws = "throws"
+
+    return (
+        func_prefix,
+        name_prefix,
+        name,
+        arglist,
+        return_intent,
+        return_type,
+        throws,
+        where_clause,
+    )
+
+
 # regex for parsing attribute and data directives.
 chpl_attr_sig_pattern = re.compile(
     r"""^ ((?:\w+\s+)*)?          # optional: prefixes
@@ -210,25 +266,25 @@ def _pseudo_parse_arglist(signode, arglist):
             signode += paramlist
 
     @staticmethod
-    def _handle_signature_suffix(signode, retann, anno, where_clause):
+    def _handle_signature_suffix(
+        signode, return_intent, return_type, throws, anno, where_clause
+    ):
         """
         handle the signature suffix items like return intent, return type,
         where clause, annotation, etc.
         """
-        if retann:
-            if ':' in retann:
-                retintent, _, rettype = retann.partition(':')
-                rettype = rettype.strip()
-            else:
-                retintent, rettype = retann, None
-            retintent = retintent.strip()
-            if retintent:
-                signode += addnodes.desc_sig_space(' ', ' ')
-                signode += addnodes.desc_annotation(' ' + retintent,
-                                                    ' ' + retintent)
-            if rettype:
-                signode += addnodes.desc_annotation(' : ' + rettype,
-                                                    ' : ' + rettype)
+
+        if return_intent:
+            signode += addnodes.desc_sig_space(' ', ' ')
+            signode += addnodes.desc_annotation(' ' + return_intent,
+                                                ' ' + return_intent)
+        if return_type:
+            signode += addnodes.desc_sig_space(' ', ' ')
+            signode += addnodes.desc_annotation(' : ' + return_type,
+                                                ' : ' + return_type)
+        if throws:
+            signode += addnodes.desc_sig_space(' ', ' ')
+            signode += addnodes.desc_annotation(' throws', ' throws')
         if anno:
             signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
         if where_clause:
@@ -253,11 +309,11 @@ def _get_proc_like_prefix(self, sig):
         """Return prefix text for function or method directive
         (and similar).
         """
-        sig_match = chpl_sig_pattern.match(sig)
+        sig_match = match_chpl_sig_pattern(sig)
         if sig_match is None:
             return ChapelObject.get_signature_prefix(self, sig)
 
-        prefixes, _, _, _, _, _ = sig_match.groups()
+        prefixes = sig_match[0]
         if prefixes:
             return prefixes.strip() + ' '
         elif self.objtype.startswith('iter'):
@@ -321,16 +377,26 @@ def handle_signature(self, sig, signode):
             sig_match = chpl_attr_sig_pattern.match(sig)
             if sig_match is None:
                 raise ValueError('Signature does not parse: {0}'.format(sig))
-            func_prefix, name_prefix, name, retann = sig_match.groups()
+            func_prefix, name_prefix, name, return_type = sig_match.groups()
+            return_intent = None
+            throws = None
             arglist = None
             where_clause = None
         else:
-            sig_match = chpl_sig_pattern.match(sig)
+            sig_match = match_chpl_sig_pattern(sig)
             if sig_match is None:
                 raise ValueError('Signature does not parse: {0}'.format(sig))
 
-            func_prefix, name_prefix, name, arglist, retann, where_clause = \
-                sig_match.groups()
+            (
+                func_prefix,
+                name_prefix,
+                name,
+                arglist,
+                return_intent,
+                return_type,
+                throws,
+                where_clause,
+            ) = sig_match
 
             # check if where clause is valid
             if where_clause is not None and not self._is_proc_like():
@@ -386,11 +452,15 @@ def handle_signature(self, sig, signode):
             if self.needs_arglist() and arglist is not None:
                 # for callables, add an empty parameter list
                 signode += addnodes.desc_parameterlist()
-            self._handle_signature_suffix(signode, retann, anno, where_clause)
+            self._handle_signature_suffix(
+                signode, return_intent, return_type, throws, anno, where_clause
+            )
             return fullname, name_prefix
 
         self._pseudo_parse_arglist(signode, arglist)
-        self._handle_signature_suffix(signode, retann, anno, where_clause)
+        self._handle_signature_suffix(
+            signode, return_intent, return_type, throws, anno, where_clause
+        )
 
         return fullname, name_prefix