Improve comments, fix doc string errors

pandas/core/frame.py

@@ -4382,8 +4382,8 @@ def duplicated(self, subset=None, keep='first', return_inverse=False):
         set on False and all others on True:
 
         >>> data = {'species': ['lama', 'cow', 'lama', 'ant', 'lama', 'bee'],
-                    'type': ['mammal'] * 3 + ['insect', 'mammal', 'insect']}
-        >>> animals = pd.DataFrame(data, index=[1, 4, 9, 16, 25])
+        ...         'type': ['mammal'] * 3 + ['insect', 'mammal', 'insect']}
+        >>> animals = pd.DataFrame(data, index=[1, 4, 9, 16, 25, 36])
         >>> animals
            species    type
         1     lama  mammal

pandas/core/series.py

@@ -1633,7 +1633,7 @@ def duplicated(self, keep='first', return_inverse=False):
         set on False and all others on True:
 
         >>> animals = pd.Series(['lama', 'cow', 'lama', 'beetle', 'lama'],
-                                index=[1, 4, 9, 16, 25])
+        ...                     index=[1, 4, 9, 16, 25])
         >>> animals.duplicated()
         1     False
         4     False

pandas/tests/indexes/common.py

@@ -406,7 +406,9 @@ def test_duplicated_inverse(self, indices, keep):
                                                   return_inverse=True)
         tm.assert_numpy_array_equal(result_isdup, expected_isdup)
 
-        # test that result_inv works (and fits together with expected_isdup)
+        # the following tests the correctness of result_inv in two ways:
+        # - it needs to fit together with expected_isdup
+        # - it needs to correctly reconstruct the object
         unique = idx[~expected_isdup]
         reconstr = unique[result_inv]
         tm.assert_index_equal(reconstr, idx)