Test in scripts/validate_docstrings.py that the short summary is always one line long (#22617)

Author: Moisan

scripts/tests/test_validate_docstrings.py

@@ -362,6 +362,15 @@ def multi_line(self):
         which is not correct.
         """
 
+    def two_paragraph_multi_line(self):
+        """
+        Extends beyond one line
+        which is not correct.
+
+        Extends beyond one line, which in itself is correct but the
+        previous short summary should still be an issue.
+        """
+
 
 class BadParameters(object):
     """
@@ -556,7 +565,9 @@ def test_bad_generic_functions(self, func):
         ('BadSummaries', 'no_capitalization',
          ('Summary must start with infinitive verb',)),
         ('BadSummaries', 'multi_line',
-         ('a short summary in a single line should be present',)),
+         ('Summary should fit in a single line.',)),
+        ('BadSummaries', 'two_paragraph_multi_line',
+         ('Summary should fit in a single line.',)),
         # Parameters tests
         ('BadParameters', 'missing_params',
          ('Parameters {**kwargs} not documented',)),

scripts/validate_docstrings.py

@@ -163,10 +163,12 @@ def double_blank_lines(self):
 
     @property
     def summary(self):
-        if not self.doc['Extended Summary'] and len(self.doc['Summary']) > 1:
-            return ''
         return ' '.join(self.doc['Summary'])
 
+    @property
+    def num_summary_lines(self):
+        return len(self.doc['Summary'])
+
     @property
     def extended_summary(self):
         if not self.doc['Extended Summary'] and len(self.doc['Summary']) > 1:
@@ -452,6 +454,8 @@ def validate_one(func_name):
             errs.append('Summary must start with infinitive verb, '
                         'not third person (e.g. use "Generate" instead of '
                         '"Generates")')
+        if doc.num_summary_lines > 1:
+            errs.append("Summary should fit in a single line.")
     if not doc.extended_summary:
         wrns.append('No extended summary found')