DOC: Update Categorical/CategoricalDtype methods' docstring to pass docstring validation (pandas-dev#58079)

* Improve docstring for some methods in categorical/categoricaldtype

* Remove cat.ordered

---------

Co-authored-by: Abdulaziz Aloqeely <[email protected]>

Author: Aloqeely

ci/code_checks.sh

@@ -70,15 +70,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         --format=actions \
         -i ES01 `# For now it is ok if docstrings are missing the extended summary` \
         -i "pandas.Series.dt PR01" `# Accessors are implemented as classes, but we do not document the Parameters section` \
-        -i "pandas.Categorical.__array__ SA01" \
-        -i "pandas.Categorical.codes SA01" \
-        -i "pandas.Categorical.dtype SA01" \
-        -i "pandas.Categorical.from_codes SA01" \
-        -i "pandas.Categorical.ordered SA01" \
-        -i "pandas.CategoricalDtype.categories SA01" \
-        -i "pandas.CategoricalDtype.ordered SA01" \
-        -i "pandas.CategoricalIndex.codes SA01" \
-        -i "pandas.CategoricalIndex.ordered SA01" \
         -i "pandas.DataFrame.__dataframe__ SA01" \
         -i "pandas.DataFrame.at_time PR01" \
         -i "pandas.DataFrame.kurt RT03,SA01" \
@@ -215,7 +206,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then
         -i "pandas.Series.cat.as_ordered PR01" \
         -i "pandas.Series.cat.as_unordered PR01" \
         -i "pandas.Series.cat.codes SA01" \
-        -i "pandas.Series.cat.ordered SA01" \
         -i "pandas.Series.cat.remove_categories PR01,PR02" \
         -i "pandas.Series.cat.remove_unused_categories PR01" \
         -i "pandas.Series.cat.rename_categories PR01,PR02" \

pandas/core/arrays/categorical.py

@@ -497,6 +497,11 @@ def dtype(self) -> CategoricalDtype:
         """
         The :class:`~pandas.api.types.CategoricalDtype` for this instance.
 
+        See Also
+        --------
+        astype : Cast argument to a specified dtype.
+        CategoricalDtype : Type for categorical data.
+
         Examples
         --------
         >>> cat = pd.Categorical(["a", "b"], ordered=True)
@@ -721,6 +726,11 @@ def from_codes(
         -------
         Categorical
 
+        See Also
+        --------
+        codes : The category codes of the categorical.
+        CategoricalIndex : An Index with an underlying ``Categorical``.
+
         Examples
         --------
         >>> dtype = pd.CategoricalDtype(["a", "b"], ordered=True)
@@ -810,6 +820,12 @@ def ordered(self) -> Ordered:
         """
         Whether the categories have an ordered relationship.
 
+        See Also
+        --------
+        set_ordered : Set the ordered attribute.
+        as_ordered : Set the Categorical to be ordered.
+        as_unordered : Set the Categorical to be unordered.
+
         Examples
         --------
         For :class:`pandas.Series`:
@@ -861,6 +877,11 @@ def codes(self) -> np.ndarray:
         ndarray[int]
             A non-writable view of the ``codes`` array.
 
+        See Also
+        --------
+        Categorical.from_codes : Make a Categorical from codes.
+        CategoricalIndex : An Index with an underlying ``Categorical``.
+
         Examples
         --------
         For :class:`pandas.Categorical`:
@@ -1641,6 +1662,9 @@ def __array__(
         """
         The numpy array interface.
 
+        Users should not call this directly. Rather, it is invoked by
+        :func:`numpy.array` and :func:`numpy.asarray`.
+
         Parameters
         ----------
         dtype : np.dtype or None
@@ -1656,6 +1680,10 @@ def __array__(
             if dtype==None (default), the same dtype as
             categorical.categories.dtype.
 
+        See Also
+        --------
+        numpy.asarray : Convert input to numpy.ndarray.
+
         Examples
         --------
 

pandas/core/dtypes/dtypes.py

@@ -623,6 +623,10 @@ def categories(self) -> Index:
         """
         An ``Index`` containing the unique categories allowed.
 
+        See Also
+        --------
+        ordered : Whether the categories have an ordered relationship.
+
         Examples
         --------
         >>> cat_type = pd.CategoricalDtype(categories=["a", "b"], ordered=True)
@@ -636,6 +640,10 @@ def ordered(self) -> Ordered:
         """
         Whether the categories have an ordered relationship.
 
+        See Also
+        --------
+        categories : An Index containing the unique categories allowed.
+
         Examples
         --------
         >>> cat_type = pd.CategoricalDtype(categories=["a", "b"], ordered=True)