gh-39375: adding some annotations in polyhedral complex
    
add some typing annotations in one file

also some minor code changes

### 📝 Checklist

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
    
URL: #39375
Reported by: Frédéric Chapoton
Reviewer(s): David Coudert

Author: Release Manager

src/sage/geometry/polyhedral_complex.py

@@ -269,7 +269,7 @@ class PolyhedralComplex(GenericCellComplex):
     """
     def __init__(self, maximal_cells=None, backend=None, maximality_check=True,
                  face_to_face_check=False, is_mutable=True, is_immutable=False,
-                 ambient_dim=None):
+                 ambient_dim=None) -> None:
         r"""
         Define a PolyhedralComplex.
 
@@ -341,7 +341,7 @@ def __init__(self, maximal_cells=None, backend=None, maximality_check=True,
         if not is_mutable or is_immutable:
             self.set_immutable()
 
-    def cells(self, subcomplex=None):
+    def cells(self, subcomplex=None) -> dict:
         """
         The cells of this polyhedral complex, in the form of a dictionary:
         the keys are integers, representing dimension, and the value
@@ -419,7 +419,7 @@ def cell_iterator(self, increasing=True):
             if d in cells:
                 yield from cells[d]
 
-    def _n_cells_sorted(self, n, subcomplex=None):
+    def _n_cells_sorted(self, n, subcomplex=None) -> list:
         """
         Sorted list of cells of dimension ``n`` of this polyhedral complex.
 
@@ -447,7 +447,7 @@ def _n_cells_sorted(self, n, subcomplex=None):
         return sorted(n_cells,
                       key=lambda p: (p.vertices(), p.rays(), p.lines()))
 
-    def cells_sorted(self, subcomplex=None):
+    def cells_sorted(self, subcomplex=None) -> list:
         """
         The sorted list of the cells of this polyhedral complex
         in non-increasing dimensions.
@@ -469,10 +469,10 @@ def cells_sorted(self, subcomplex=None):
         """
         cells = []
         for n in range(self._dim, -1, -1):
-            cells += self._n_cells_sorted(n, subcomplex)
+            cells.extend(self._n_cells_sorted(n, subcomplex))
         return cells
 
-    def maximal_cells(self):
+    def maximal_cells(self) -> dict:
         """
         The maximal cells of this polyhedral complex, in the form of a
         dictionary: the keys are integers, representing dimension, and the
@@ -546,7 +546,7 @@ def maximal_cell_iterator(self, increasing=False):
             if d in maximal_cells:
                 yield from maximal_cells[d]
 
-    def n_maximal_cells(self, n):
+    def n_maximal_cells(self, n) -> list:
         r"""
         List of maximal cells of dimension ``n`` of this polyhedral complex.
 
@@ -584,10 +584,9 @@ def n_maximal_cells(self, n):
         """
         if n in self.maximal_cells():
             return list(self.maximal_cells()[n])
-        else:
-            return []
+        return []
 
-    def _n_maximal_cells_sorted(self, n):
+    def _n_maximal_cells_sorted(self, n) -> list:
         """
         Sorted list of maximal cells of dimension ``n`` of this polyhedral
         complex.
@@ -613,7 +612,7 @@ def _n_maximal_cells_sorted(self, n):
         return sorted(n_maximal_cells,
                       key=lambda p: (p.vertices(), p.rays(), p.lines()))
 
-    def maximal_cells_sorted(self):
+    def maximal_cells_sorted(self) -> list:
         """
         Return the sorted list of the maximal cells of this polyhedral complex
         by non-increasing dimensions.
@@ -629,11 +628,11 @@ def maximal_cells_sorted(self):
         if self._maximal_cells_sorted is None:
             maximal_cells = []
             for n in range(self._dim, -1, -1):
-                maximal_cells += self._n_maximal_cells_sorted(n)
+                maximal_cells.extend(self._n_maximal_cells_sorted(n))
             self._maximal_cells_sorted = maximal_cells
         return self._maximal_cells_sorted
 
-    def is_maximal_cell(self, c):
+    def is_maximal_cell(self, c) -> bool:
         """
         Return whether the given cell ``c`` is a maximal cell of ``self``.
 
@@ -664,7 +663,7 @@ def is_maximal_cell(self, c):
         # return (c in self.n_maximal_cells(d)) # use set instead of list
         return (d in self.maximal_cells()) and (c in self.maximal_cells()[d])
 
-    def is_cell(self, c):
+    def is_cell(self, c) -> bool:
         """
         Return whether the given cell ``c`` is a cell of ``self``.
 
@@ -798,7 +797,7 @@ def plot(self, **kwds):
             g += cell.plot(**options)
         return g
 
-    def is_pure(self):
+    def is_pure(self) -> bool:
         """
         Test if this polyhedral complex is pure.
 
@@ -828,10 +827,11 @@ def is_pure(self):
         """
         return len(self._maximal_cells) == 1
 
-    def is_full_dimensional(self):
+    def is_full_dimensional(self) -> bool:
         """
-        Return whether this polyhedral complex is full-dimensional:
-        its dimension is equal to its ambient dimension.
+        Return whether this polyhedral complex is full-dimensional.
+
+        This means that its dimension is equal to its ambient dimension.
 
         EXAMPLES::
 
@@ -846,7 +846,7 @@ def is_full_dimensional(self):
         """
         return self._dim == self._ambient_dim
 
-    def __hash__(self):
+    def __hash__(self) -> int:
         """
         Compute the hash value of ``self`` using its ``maximal_cells_sorted``.
 
@@ -871,7 +871,7 @@ def __hash__(self):
                              "call set_immutable()")
         return hash(tuple(self.maximal_cells_sorted()))
 
-    def __eq__(self, right):
+    def __eq__(self, right) -> bool:
         """
         Two polyhedral complexes are equal iff their maximal cells are equal.
 
@@ -889,7 +889,7 @@ def __eq__(self, right):
         return isinstance(right, PolyhedralComplex) and (
                self.maximal_cells_sorted() == right.maximal_cells_sorted())
 
-    def __ne__(self, right):
+    def __ne__(self, right) -> bool:
         """
         Return ``True`` if ``self`` and ``right`` are not equal.
 
@@ -943,7 +943,7 @@ def _an_element_(self):
             from sage.categories.sets_cat import EmptySetError
             raise EmptySetError("the complex is empty")
 
-    def __contains__(self, x):
+    def __contains__(self, x) -> bool:
         """
         Return ``True`` if ``x`` is a polyhedron which is contained in this complex.
 
@@ -1031,7 +1031,7 @@ def face_poset(self):
             self.cells()    # poset is obtained and cached in cells()
         return self._face_poset
 
-    def is_subcomplex(self, other):
+    def is_subcomplex(self, other) -> bool:
         r"""
         Return whether ``self`` is a subcomplex of ``other``.
 
@@ -1059,7 +1059,7 @@ def is_subcomplex(self, other):
                 return False
         return True
 
-    def is_compact(self):
+    def is_compact(self) -> bool:
         """
         Test for boundedness of the polyhedral complex.
 
@@ -1128,7 +1128,7 @@ def graph(self):
             d[v] = []
         return Graph(d)
 
-    def is_connected(self):
+    def is_connected(self) -> bool:
         """
         Return whether ``self`` is connected.
 
@@ -1252,7 +1252,7 @@ def connected_component(self, cell=None):
                                  is_immutable=self._is_immutable,
                                  backend=self._backend)
 
-    def connected_components(self):
+    def connected_components(self) -> list:
         """
         Return the connected components of this polyhedral complex,
         as list of (sub-)PolyhedralComplexes.
@@ -1303,11 +1303,10 @@ def connected_components(self):
             lists_of_facets = [
                 [f for f in self.maximal_cell_iterator() if f in faces]
                 for faces in lists_of_faces]
-        results = [PolyhedralComplex(facets, maximality_check=False,
-                                     is_immutable=self._is_immutable,
-                                     backend=self._backend)
-                   for facets in lists_of_facets]
-        return results
+        return [PolyhedralComplex(facets, maximality_check=False,
+                                  is_immutable=self._is_immutable,
+                                  backend=self._backend)
+                for facets in lists_of_facets]
 
     def n_skeleton(self, n):
         r"""
@@ -1445,7 +1444,7 @@ def boundary_subcomplex(self):
                 ans.set_immutable()
             return ans
 
-    def relative_boundary_cells(self):
+    def relative_boundary_cells(self) -> list:
         r"""
         Return the maximal cells of the relative-boundary sub-complex.
 
@@ -1501,10 +1500,10 @@ def relative_boundary_cells(self):
         faces = self.n_cells(d - 1)
         ans = [face for face in faces if len(poset.upper_covers(face)) == 1]
         if not self.is_pure():
-            ans += [p for p in poset.maximal_elements() if p.dimension() < d]
+            ans.extend(p for p in poset.maximal_elements() if p.dimension() < d)
         return ans
 
-    def is_convex(self):
+    def is_convex(self) -> bool:
         r"""
         Return whether the set of points in ``self`` is a convex set.
 
@@ -1863,7 +1862,7 @@ def alexander_whitney(self, cell, dim_left):
     # this function overrides the standard one for GenericCellComplex,
     # this one counts the number of maximal cells, not all cells, to
     # avoid calling and computing self.cells()
-    def _repr_(self):
+    def _repr_(self) -> str:
         """
         Print representation.
 
@@ -1891,7 +1890,7 @@ def _repr_(self):
         else:
             return "Polyhedral complex with %s maximal cells" % num
 
-    def set_immutable(self):
+    def set_immutable(self) -> None:
         """
         Make this polyhedral complex immutable.
 
@@ -1906,7 +1905,7 @@ def set_immutable(self):
         """
         self._is_immutable = True
 
-    def is_mutable(self):
+    def is_mutable(self) -> bool:
         """
         Return whether ``self`` is mutable.
 
@@ -1930,7 +1929,7 @@ def is_mutable(self):
         """
         return not self._is_immutable
 
-    def is_immutable(self):
+    def is_immutable(self) -> bool:
         """
         Return whether ``self`` is immutable.
 
@@ -2224,7 +2223,7 @@ def remove_cell(self, cell, check=False):
         self._is_convex = None
         self._polyhedron = None
 
-    def is_simplicial_complex(self):
+    def is_simplicial_complex(self) -> bool:
         """
         Test if this polyhedral complex is a simplicial complex.
 
@@ -2243,7 +2242,7 @@ def is_simplicial_complex(self):
         """
         return all(p.is_simplex() for p in self.maximal_cell_iterator())
 
-    def is_polyhedral_fan(self):
+    def is_polyhedral_fan(self) -> bool:
         """
         Test if this polyhedral complex is a polyhedral fan.
 
@@ -2266,7 +2265,7 @@ def is_polyhedral_fan(self):
                    vector(p.vertices_list()[0]) == p.ambient_space().zero())
                    for p in self.maximal_cell_iterator())
 
-    def is_simplicial_fan(self):
+    def is_simplicial_fan(self) -> bool:
         """
         Test if this polyhedral complex is a simplicial fan.
 
@@ -2470,7 +2469,7 @@ def subdivide(self, make_simplicial=False,
 ############################################################
 
 
-def cells_list_to_cells_dict(cells_list):
+def cells_list_to_cells_dict(cells_list) -> dict:
     r"""
     Helper function that returns the dictionary whose keys are the dimensions,
     and the value associated to an integer `d` is the set of `d`-dimensional