ENH: Allow a trailing COMMA or PERIOD in a See Also function list block.

Only trigger the trailing comma warning if there is also a description on the
same line.
Added a test that the warning is generated.

Author: pvanmulbregt

numpydoc/docscrape.py

@@ -245,7 +245,7 @@ def _parse_param_list(self, content, single_element_is_type=False):
     #
     # <FUNCNAME>
     # <FUNCNAME> SPACE* COLON SPACE+ <DESC> SPACE*
-    # <FUNCNAME> ( COMMA SPACE+ <FUNCNAME>)* SPACE*
+    # <FUNCNAME> ( COMMA SPACE+ <FUNCNAME>)+ (COMMA | PERIOD)? SPACE*
     # <FUNCNAME> ( COMMA SPACE+ <FUNCNAME>)* SPACE* COLON SPACE+ <DESC> SPACE*
 
     # <FUNCNAME> is one of
@@ -258,8 +258,8 @@ def _parse_param_list(self, content, single_element_is_type=False):
     # <DESC> is a string describing the function.
 
     _role = r":(?P<role>\w+):"
-    _funcbacktick = r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_.-]+)`"
-    _funcplain = r"(?P<name2>[a-zA-Z0-9_.-]+)"
+    _funcbacktick = r"`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`"
+    _funcplain = r"(?P<name2>[a-zA-Z0-9_\.-]+)"
     _funcname = r"(" + _role + _funcbacktick + r"|" + _funcplain + r")"
     _funcnamenext = _funcname.replace('role', 'rolenext')
     _funcnamenext = _funcnamenext.replace('name', 'namenext')
@@ -271,7 +271,7 @@ def _parse_param_list(self, content, single_element_is_type=False):
         _funcname +
         r"(?P<morefuncs>([,]\s+" + _funcnamenext + r")*)" +
         r")" +                     # end of "allfuncs"
-        r"(?P<trailing>\s*,)?" +   # Some function lists have a trailing comma
+        r"(?P<trailing>[,\.])?" +   # Some function lists have a trailing comma (or period)  '\s*'
         _description)
 
     # Empty <DESC> elements are replaced with '..'
@@ -306,9 +306,9 @@ def parse_item_name(text):
             description = None
             if line_match:
                 description = line_match.group('desc')
-                if line_match.group('trailing'):
+                if line_match.group('trailing') and description:
                     self._error_location(
-                        'Unexpected comma after function list at index %d of '
+                        'Unexpected comma or period after function list at index %d of '
                         'line "%s"' % (line_match.end('trailing'), line),
                         error=False)
             if not description and line.startswith(' '):

numpydoc/tests/test_docscrape.py

@@ -17,6 +17,7 @@
 from numpydoc.docscrape_sphinx import (SphinxDocString, SphinxClassDoc,
                                        SphinxFunctionDoc, get_doc_object)
 from pytest import raises as assert_raises
+from pytest import warns as assert_warns
 
 
 if sys.version_info[0] >= 3:
@@ -859,6 +860,21 @@ class Dummy(object):
     assert(':func:`func_d`' in s)
 
 
+def test_see_also_trailing_comma_warning():
+    warnings.filterwarnings('error')
+    with assert_warns(Warning, match='Unexpected comma or period after function list at index 43 of line .*'):
+        doc6 = NumpyDocString(
+            """
+            z(x,theta)
+
+            See Also
+            --------
+            func_f2, func_g2, :meth:`func_h2`, func_j2, : description of multiple
+            :class:`class_j`: fubar
+                foobar
+            """)
+
+
 def test_unknown_section():
     doc_text = """
 Test having an unknown section