From 5fe8af26daa05402588bb90b4ada76d629cacc31 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Fri, 10 Jul 2020 15:37:42 -0700
Subject: [PATCH 1/2] 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.
---
 numpydoc/docscrape.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/numpydoc/docscrape.py b/numpydoc/docscrape.py
index ad0d99cd..320f9d51 100644
--- a/numpydoc/docscrape.py
+++ b/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'):

From 3ade819641f78bf2714032d70866f47a52b9c743 Mon Sep 17 00:00:00 2001
From: Matthias Bussonnier <bussonniermatthias@gmail.com>
Date: Tue, 14 Jul 2020 09:05:01 -0700
Subject: [PATCH 2/2] add warn test

---
 numpydoc/tests/test_validate.py | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/numpydoc/tests/test_validate.py b/numpydoc/tests/test_validate.py
index b7127ce2..b8f4d873 100644
--- a/numpydoc/tests/test_validate.py
+++ b/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",
         [