GH15219 Documentation fixes based on feedback

Author: Justin Solinsky

doc/source/whatsnew/v0.20.0.txt

@@ -157,7 +157,7 @@ Other enhancements
 - HTML table output skips ``colspan`` or ``rowspan`` attribute if equal to 1. (:issue:`15403`)
 
 .. _ISO 8601 duration: https://en.wikipedia.org/wiki/ISO_8601#Durations
-- ``ignore_ordered`` argument added to ``pd.types.concat.union_categoricals``; setting the argument to true will ignore the ordered attribute of unioned categoricals (:issue:`13410`)
+- ``ignore_ordered`` argument added to ``pd.types.concat.union_categoricals``; setting the argument to true will ignore the ordered attribute of unioned categoricals (:issue:`13410`) .  See the :ref:`categorical union docs <categorical.union>` for more information.
 
 .. _whatsnew_0200.api_breaking:
 

pandas/tests/tools/test_concat.py

@@ -1663,17 +1663,27 @@ def test_union_categoricals_ordered(self):
             union_categoricals([c1, c2])
 
     def test_union_categoricals_ignore_order(self):
+        # GH 15219
         c1 = Categorical([1, 2, 3], ordered=True)
         c2 = Categorical([1, 2, 3], ordered=False)
 
         res = union_categoricals([c1, c2], ignore_order=True)
         exp = Categorical([1, 2, 3, 1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
+        msg = 'Categorical.ordered must be the same'
+        with tm.assertRaisesRegexp(TypeError, msg):
+            union_categoricals([c1, c2], ignore_order=False)
+
         res = union_categoricals([c1, c1], ignore_order=True)
         exp = Categorical([1, 2, 3, 1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
+        res = union_categoricals([c1, c1], ignore_order=False)
+        exp = Categorical([1, 2, 3, 1, 2, 3],
+                          categories=[1, 2, 3], ordered=True)
+        tm.assert_categorical_equal(res, exp)
+
         c1 = Categorical([1, 2, 3, np.nan], ordered=True)
         c2 = Categorical([3, 2], categories=[1, 2, 3], ordered=True)
 
@@ -1688,7 +1698,8 @@ def test_union_categoricals_ignore_order(self):
         exp = Categorical([1, 2, 3, 1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
-        res = union_categoricals([c2, c1], ignore_order=True, sort_categories=True)
+        res = union_categoricals([c2, c1], ignore_order=True,
+                                 sort_categories=True)
         exp = Categorical([1, 2, 3, 1, 2, 3], categories=[1, 2, 3])
         tm.assert_categorical_equal(res, exp)
 
@@ -1698,6 +1709,13 @@ def test_union_categoricals_ignore_order(self):
         expected = Categorical([1, 2, 3, 4, 5, 6])
         tm.assert_categorical_equal(result, expected)
 
+        msg = "to union ordered Categoricals, all categories must be the same"
+        with tm.assertRaisesRegexp(TypeError, msg):
+            union_categoricals([c1, c2], ignore_order=False)
+
+        with tm.assertRaisesRegexp(TypeError, msg):
+            union_categoricals([c1, c2])
+
     def test_union_categoricals_sort(self):
         # GH 13846
         c1 = Categorical(['x', 'y', 'z'])

pandas/types/concat.py

@@ -226,6 +226,8 @@ def union_categoricals(to_union, sort_categories=False, ignore_order=False):
         If true, the ordered attribute of the Categoricals will be ignored.
         Results in an unordered categorical.
 
+        .. versionadded:: 0.20.0
+
     Returns
     -------
     result : Categorical