ENH: Better warning for sections.

numpydoc/docscrape.py

@@ -176,6 +176,10 @@ def _is_at_section(self):
             return True
 
         l2 = self._doc.peek(1).strip()  # ---------- or ==========
+        if len(l2) >= 3 and (set(l2) in ({'-'}, {'='}) ) and len(l2) != len(l1):
+            snip = '\n'.join(self._doc._str[:2])+'...'
+            self._error_location("potentially wrong underline length... \n%s \n%s in \n%s"\
+                    % (l1, l2, snip), error=False)
         return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1))
 
     def _strip(self, doc):
@@ -387,8 +391,8 @@ def _parse(self):
                 section = (s.capitalize() for s in section.split(' '))
                 section = ' '.join(section)
                 if self.get(section):
-                    self._error_location("The section %s appears twice"
-                                         % section)
+                    self._error_location("The section %s appears twice in  %s"
+                            % (section, '\n'.join(self._doc._str)))
 
             if section in ('Parameters', 'Other Parameters', 'Attributes',
                            'Methods'):

numpydoc/tests/test_validate.py

@@ -585,6 +585,22 @@ def directives_without_two_colons(self, first, second):
         """
         pass
 
+class WarnGenericFormat:
+    """
+    Those contains things that _may_ be incorrect formatting.
+    """
+
+    def too_short_header_underline(self, a, b):
+        """
+        The header line is too short.
+
+        Parameters
+        ------
+        a, b : int
+            Foo bar baz.
+        """
+        pass
+
 
 class BadSummaries:
     def no_summary(self):
@@ -1037,6 +1053,20 @@ def test_bad_class(self, capsys):
         assert isinstance(errors, list)
         assert errors
 
+    @pytest.mark.parametrize(
+        "func",
+        [
+            "too_short_header_underline",
+        ],
+    )
+    def test_bad_generic_functions(self, capsys, func):
+        with pytest.warns(UserWarning):
+            errors = validate_one(
+                self._import_path(klass="WarnGenericFormat", func=func)  # noqa:F821
+                )
+        assert 'is too short' in w.msg
+
+
     @pytest.mark.parametrize(
         "func",
         [