ENH: Better warning for sections. (#278)

* ENH: Better warning for sections.

1) if the number of -/= is too short/ too long warn, Especially too
short it won't be detected as a section.

2) for duplicate section print the docstring to figure out where the
problem is.

* add warn test

2 files changed, 36 insertions, 2 deletions

diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py
index 0ee979e..0958452 100644
--- a/numpydoc/docscrape.py
+++ b/numpydoc/docscrape.py
@@ -176,6 +176,10 @@ class NumpyDocString(Mapping):
             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 @@ class NumpyDocString(Mapping):
                 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'):
diff --git a/numpydoc/tests/test_validate.py b/numpydoc/tests/test_validate.py
index b7127ce..b8f4d87 100644
--- a/numpydoc/tests/test_validate.py
+++ b/numpydoc/tests/test_validate.py
@@ -585,6 +585,22 @@ class BadGenericDocStrings:
         """
         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):
@@ -1040,6 +1056,20 @@ class TestValidator:
     @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",
+        [
             "func",
             "astype",
             "astype1",