Docstring changes to reduce numpydoc validation issues, helps with #178…

… (#325)

* Docstring changes to reduce numpydoc validation issues, helps with #178

* Making changes to docstrings to bring in line with numpydoc recommendations.

Some functions were skipped, see #326

This resolves #178

toponetx/classes/cell_complex.py

@@ -179,22 +179,46 @@ def __init__(
 
     @property
     def cells(self) -> CellView:
-        """Return cells."""
+        """Return cells.
+
+        Returns
+        -------
+        CellView
+            The cell view of the Complex.
+        """
         return self._cells
 
     @property
     def edges(self) -> EdgeView:
-        """Return edges."""
+        """Return edges.
+
+        Returns
+        -------
+        EdgeView
+            The edge view of the Complex.
+        """
         return self._G.edges
 
     @property
     def nodes(self) -> NodeView:
-        """Return nodes."""
+        """Return nodes.
+
+        Returns
+        -------
+        NodeView
+            The node view of the Complex.
+        """
         return self._G.nodes
 
     @property
     def maxdim(self) -> int:
-        """Return maximum dimension."""
+        """Return maximum dimension.
+
+        Returns
+        -------
+        int
+            The maximum dimension for Cell Complex.
+        """
         warn(
             "`CellComplex.maxdim` is deprecated and will be removed in the future, use `CellComplex.dim` instead.",
             DeprecationWarning,
@@ -204,7 +228,13 @@ def maxdim(self) -> int:
 
     @property
     def dim(self) -> int:
-        """Return maximum dimension."""
+        """Return maximum dimension.
+
+        Returns
+        -------
+        int
+            The maximum dimension of the Cell Complex.
+        """
         if len(self.nodes) == 0:
             return 0
         if len(self.edges) == 0:
@@ -217,8 +247,11 @@ def dim(self) -> int:
     def shape(self) -> tuple[int, int, int]:
         """Return shape.
 
-        This is:
-        (number of cells[i], for i in range(0, dim(CC)))
+        Returns
+        -------
+        tuple[int, int, int]
+            The tuple containing the number of entities corresponding to the
+            nodes, edges, and cells of the Cell Complex respectively.
         """
         return len(self.nodes), len(self.edges), len(self.cells)
 
@@ -255,6 +288,7 @@ def is_regular(self) -> bool:
         Returns
         -------
         bool
+            Returns `True` if the regularity condition is satisfied.
 
         Examples
         --------
@@ -272,15 +306,33 @@ def is_regular(self) -> bool:
         return True
 
     def __str__(self) -> str:
-        """Return detailed string representation."""
+        """Return detailed string representation.
+
+        Returns
+        -------
+        str
+            The string representation of the Cell Complex.
+        """
         return f"Cell Complex with {len(self.nodes)} nodes, {len(self.edges)} edges and {len(self.cells)} 2-cells "
 
     def __repr__(self) -> str:
-        """Return string representation."""
+        """Return string representation.
+
+        Returns
+        -------
+        str
+            The __repr__ representation of the Cell Complex.
+        """
         return f"CellComplex(name='{self.name}')"
 
     def __len__(self) -> int:
-        """Return number of nodes."""
+        """Return number of nodes.
+
+        Returns
+        -------
+        int
+            The number of nodes in the Cell Complex.
+        """
         return len(self.nodes)
 
     def __iter__(self) -> Iterator:
@@ -314,16 +366,25 @@ def __getitem__(self, node):
         Parameters
         ----------
         node : hashable
+            The node contained in the cell complex.
 
         Returns
         -------
-        neighbors(node) : iterator
+        Iterator
             Iterator over neighbors of node.
         """
         return self.neighbors(node)
 
     def _insert_cell(self, cell: tuple | list | Cell, **attr):
-        """Insert cell."""
+        """Insert cell.
+
+        Parameters
+        ----------
+        cell : tuple | list | Cell
+            The cell to insert.
+        **attr
+            The attributes of the cell to insert.
+        """
         # input must be list, tuple or Cell type
         if isinstance(cell, (tuple, list, Cell)):
             if isinstance(cell, (tuple, list)):
@@ -342,7 +403,15 @@ def _insert_cell(self, cell: tuple | list | Cell, **attr):
             raise TypeError("input must be list, tuple or Cell type")
 
     def _delete_cell(self, cell: tuple | list | Cell, key=None):
-        """Delete cell."""
+        """Delete cell.
+
+        Parameters
+        ----------
+        cell : tuple | list | Cell
+            The cell to delete.
+        key : Hashable
+            The key of the cell to delete.
+        """
         if isinstance(cell, Cell):
             cell = cell.elements
         if cell in self._cells._cells:
@@ -360,8 +429,8 @@ def _cell_equivalence_class(self) -> dict[Cell, set[Cell]]:
 
         Returns
         -------
-        equiv : dict[Cell, set[Cell]]
-            Dict structure: `Cell` representing equivalence class -> Set of all `Cell`s in class
+        dict[Cell, set[Cell]]
+            Dict structure: `Cell` representing equivalence class -> Set of all `Cell`s in class.
 
         Examples
         --------
@@ -649,6 +718,7 @@ def _add_nodes_from(self, nodes: Iterable[Hashable]) -> None:
         Parameters
         ----------
         nodes : iterable of hashables
+            Nodes to instantiate when adding cells to cell complex.
         """
         for node in nodes:
             self.add_node(node)
@@ -2368,6 +2438,11 @@ def from_trimesh(cls, mesh) -> "CellComplex":
         mesh : trimesh.Trimesh
             A trimesh object.
 
+        Returns
+        -------
+        CellComplex
+            The cell complex generated from the trimesh provided.
+
         Examples
         --------
         >>> import trimesh

toponetx/classes/complex.py

@@ -27,14 +27,31 @@ class Atom(abc.ABC):
     def __init__(
         self, elements: Collection[Hashable], name: str = "", **kwargs
     ) -> None:
+        """Abstract class representing an atom in a complex.
+
+        Parameters
+        ----------
+        elements : Collection[Hashable]
+            The elements in the atom.
+        name : str, optional
+            Name of the atom.
+        **kwargs : keyword arguments, optional
+            Additional attributes to be associated with the atom.
+        """
         self.elements = elements
         self.name = name
 
         self._attributes = {}
         self._attributes.update(kwargs)
 
     def __len__(self) -> int:
-        """Return the number of elements in the atom."""
+        """Return the number of elements in the atom.
+
+        Returns
+        -------
+        int
+            The number of elements in the atom.
+        """
         return len(self.elements)
 
     def __iter__(self) -> Iterator:
@@ -43,6 +60,7 @@ def __iter__(self) -> Iterator:
         Returns
         -------
         Iterator
+            Iterator over the elements in the atom.
         """
         return iter(self.elements)
 
@@ -57,6 +75,8 @@ def __contains__(self, item: Any) -> bool:
         Returns
         -------
         bool
+            Returns `True` if the item is contained in the element
+            and `False` otherwise.
         """
         return item in self.elements
 
@@ -147,6 +167,15 @@ class Complex(abc.ABC):
     complex: dict[Any, Any]
 
     def __init__(self, name: str = "", **kwargs) -> None:
+        """Initialize a new instance of the Complex class.
+
+        Parameters
+        ----------
+        name : str, optional
+            Name of the complex.
+        **kwargs : keyword arguments, optional
+            Attributes to add to the complex as key=value pairs.
+        """
         self.name = name
         self.complex = {}
         self.complex.update(kwargs)
@@ -164,6 +193,7 @@ def dim(self) -> int:
         Returns
         -------
         int
+            Returns the dimension of the complex.
         """
 
     @property
@@ -195,6 +225,7 @@ def __str__(self) -> str:
         Returns
         -------
         str
+            Returns the string representation of the complex.
         """
 
     @abc.abstractmethod
@@ -207,6 +238,7 @@ def __repr__(self) -> str:
         Returns
         -------
         str
+            Returns the __repr__ representation of the complex.
         """
 
     @abc.abstractmethod
@@ -233,11 +265,23 @@ def __contains__(self, item: Any) -> bool:
         Returns
         -------
         bool
+            Returns `True` if the complex contains the item else `False`.
         """
 
     @abc.abstractmethod
     def __getitem__(self, key):
-        """Get item."""
+        """Get item.
+
+        Parameters
+        ----------
+        key : hashable
+            Get item based on key.
+
+        Returns
+        -------
+        Hashable
+            The hashable item that needs to be returned.
+        """
 
     @abc.abstractmethod
     def remove_nodes(self, node_set: Iterator[Hashable]) -> None:

toponetx/classes/hyperedge.py

@@ -37,6 +37,30 @@ class HyperEdge(Atom):
     def __init__(
         self, elements: Collection, name: str = "", rank=None, **kwargs
     ) -> None:
+        """Generate instance of the class for a hyperedge (or a set-type cell).
+
+        This class represents a set-type cell in a combinatorial complex, which is a set of
+        nodes with optional attributes and a rank. The nodes in a hyperedge must be
+        hashable and unique, and the hyperedge itself is immutable.
+
+        Parameters
+        ----------
+        elements : iterable of hashables
+            The nodes in the hyperedge.
+        name : str, optional
+            The name of the hyperedge.
+        rank : int, optional
+            The rank of the hyperedge. Default is None.
+        **kwargs : additional attributes
+            Additional attributes of the hyperedge, as keyword arguments.
+
+        Examples
+        --------
+        >>> ac1 = HyperEdge((1, 2, 3))
+        >>> ac2 = HyperEdge((1, 2, 4, 5))
+        >>> ac3 = HyperEdge(("a", "b", "c"))
+        >>> ac3 = HyperEdge(("a", "b", "c"), rank=10)
+        """
         for i in elements:
             if not isinstance(i, Hashable):
                 raise TypeError("Every element of HyperEdge must be hashable.")
@@ -80,6 +104,11 @@ def __hash__(self):
     def __eq__(self, other):
         """Return whether all attributes of HyperEdge objects are equal.
 
+        Parameters
+        ----------
+        other : HyperEdge
+            The other HyperEdge that needs to be compared to the current HyperEdge.
+
         Returns
         -------
         bool
@@ -92,6 +121,11 @@ def __eq__(self, other):
     def __ne__(self, other):
         """Return whether any attributes of HyperEdge objects are not equal.
 
+        Parameters
+        ----------
+        other : HyperEdge
+            The other HyperEdge that needs to be compared to the current HyperEdge.
+
         Returns
         -------
         bool