DOC: Fix GH24143

Author: aqurilla

pandas/core/indexes/base.py

@@ -2110,12 +2110,12 @@ def get_duplicates(self):
         """
         Extract duplicated index elements.
 
-        Returns a sorted list of index elements which appear more than once in
-        the index.
-
         .. deprecated:: 0.23.0
             Use idx[idx.duplicated()].unique() instead
 
+        Returns a sorted list of index elements which appear more than once in
+        the index.
+
         Returns
         -------
         array-like

pandas/core/indexes/multi.py

@@ -1484,11 +1484,11 @@ def to_hierarchical(self, n_repeat, n_shuffle=1):
         Return a MultiIndex reshaped to conform to the
         shapes given by n_repeat and n_shuffle.
 
+        .. deprecated:: 0.24.0
+
         Useful to replicate and rearrange a MultiIndex for combination
         with another Index with n_repeat items.
 
-        .. deprecated:: 0.24.0
-
         Parameters
         ----------
         n_repeat : int

pandas/core/series.py

@@ -1082,12 +1082,12 @@ def set_value(self, label, value, takeable=False):
         """
         Quickly set single value at passed label.
 
-        If label is not contained, a new object is created with the label
-        placed at the end of the result index.
-
         .. deprecated:: 0.21.0
             Please use .at[] or .iat[] accessors.
 
+        If label is not contained, a new object is created with the label
+        placed at the end of the result index.
+
         Parameters
         ----------
         label : object

pandas/io/stata.py

@@ -119,8 +119,8 @@
 _data_method_doc = """\
 Reads observations from Stata file, converting them into a dataframe
 
-    .. deprecated::
-       This is a legacy method.  Use `read` in new code.
+.. deprecated::
+    This is a legacy method.  Use `read` in new code.
 
 Parameters
 ----------

scripts/tests/test_validate_docstrings.py

@@ -407,6 +407,20 @@ def sections_in_wrong_order(self):
             before Examples.
         """
 
+    def deprecation_in_wrong_order(self):
+        """
+        This is what old method does.
+
+        This is an extended summary with more details about
+        what `some_old_method` does.
+
+        The extended summary can contain multiple paragraphs.
+
+        .. deprecated:: 1.0
+            This should generate an error as it needs to go before
+            extended summary.
+        """
+
     def method_wo_docstrings(self):
         pass
 
@@ -772,6 +786,8 @@ def test_bad_generic_functions(self, func):
         ('BadGenericDocStrings', 'sections_in_wrong_order',
          ('Sections are in the wrong order. Correct order is: Parameters, '
           'See Also, Examples',)),
+        ('BadGenericDocStrings', 'deprecation_in_wrong_order',
+         ('Deprecation warning should precede extended summary',)),
         ('BadSeeAlso', 'desc_no_period',
          ('Missing period at end of description for See Also "Series.iloc"',)),
         ('BadSeeAlso', 'desc_first_letter_lowercase',

scripts/validate_docstrings.py

@@ -79,6 +79,7 @@
     'GL07': 'Sections are in the wrong order. Correct order is: '
             '{correct_sections}',
     'GL08': 'The object does not have a docstring',
+    'GL09': 'Deprecation warning should precede extended summary',
     'SS01': 'No summary found (a short summary in a single line should be '
             'present at the beginning of the docstring)',
     'SS02': 'Summary does not start with a capital letter',
@@ -624,6 +625,10 @@ def get_validation_data(doc):
         errs.append(error('GL07',
                           correct_sections=', '.join(correct_order)))
 
+    if (doc.deprecated and not doc.name.startswith('pandas.Panel')
+            and not doc.extended_summary.startswith('.. deprecated:: ')):
+        errs.append(error('GL09'))
+
     if not doc.summary:
         errs.append(error('SS01'))
     else:
@@ -857,6 +862,7 @@ def header(title, width=80, char='#'):
 
     else:
         result = validate_one(func_name)
+
         sys.stderr.write(header('Docstring ({})'.format(func_name)))
         sys.stderr.write('{}\n'.format(result['docstring']))
         sys.stderr.write(header('Validation'))