Be explicit in that Index and CTableIndex are essentially the same concept

Author: FrancescAlted

doc/reference/ctable.rst

@@ -265,10 +265,12 @@ Indexes
 -------
 
 CTable indexes are created with :meth:`CTable.create_index` and returned as
-:class:`blosc2.ctable.CTableIndex` handles.  A ``CTableIndex`` is the table
-counterpart to :class:`blosc2.Index`: it refers to an index stored in the table
-index catalog, and delegates maintenance operations such as ``drop()``,
-``rebuild()``, and ``compact()`` back to the owning table.
+:class:`blosc2.ctable.CTableIndex` handles.  ``CTableIndex`` has the same
+user-facing role as :class:`blosc2.Index`, but for tables instead of arrays:
+it refers to an index stored in the table index catalog, and delegates
+maintenance operations such as ``drop()``, ``rebuild()``, and ``compact()``
+back to the owning table.  Users normally only receive these handles from the
+CTable API; they do not instantiate them directly.
 
 Indexes can target stored columns or **direct expressions** over stored columns
 via ``create_index(expression=...)``.  This lets queries reuse indexes for

doc/reference/index_class.rst

@@ -11,8 +11,10 @@ Handle for an index attached to a :class:`~blosc2.NDArray`.
 storage usage, or to drop, rebuild, and compact the index.  Users normally do
 not instantiate ``Index`` directly.
 
-For table indexes, see :class:`blosc2.ctable.CTableIndex`, documented in the
-:ref:`CTable` reference.
+For table indexes, :class:`blosc2.ctable.CTableIndex` plays the same
+user-facing role for :class:`~blosc2.CTable` objects.  It is documented in the
+:ref:`CTable` reference because table indexes can target columns and table
+expressions.
 
 .. currentmodule:: blosc2
 

src/blosc2/ctable.py

@@ -240,11 +240,13 @@ def __getitem__(self, key):
 
 
 class CTableIndex:
-    """A handle on an index attached to a :class:`CTable` target.
+    """Handle for an index attached to a :class:`CTable` target.
 
-    Returned by :meth:`CTable.index` and items of :attr:`CTable.indexes`.
-    Provides :meth:`drop`, :meth:`rebuild`, and :meth:`compact` convenience
-    methods that delegate back to the owning table.
+    This has the same user-facing role as :class:`blosc2.Index`, but for
+    tables instead of arrays.  It is returned by :meth:`CTable.create_index`,
+    :meth:`CTable.index`, and items of :attr:`CTable.indexes`, and provides
+    the same core convenience operations: :meth:`drop`, :meth:`rebuild`, and
+    :meth:`compact`.  Users should not instantiate this class directly.
     """
 
     def __init__(self, table: CTable, col_name: str, descriptor: dict) -> None:

src/blosc2/indexing.py

@@ -4040,7 +4040,9 @@ class Index(Mapping):
     :meth:`blosc2.NDArray.create_index`, :meth:`blosc2.NDArray.index`, and
     :attr:`blosc2.NDArray.indexes`.  They expose descriptor metadata and
     convenience methods for dropping, rebuilding, or compacting the underlying
-    index.  Users should not instantiate this class directly.
+    index.  :class:`blosc2.ctable.CTableIndex` plays the same user-facing role
+    for :class:`blosc2.CTable` indexes.  Users should not instantiate either
+    class directly.
     """
 
     def __init__(self, array: blosc2.NDArray, token: str):