Document argument is_open in ManifoldSubset.complement and differnce

Author: egourgoulhon

src/sage/manifolds/subset.py

@@ -2629,11 +2629,13 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False):
         - ``latex_name`` --  (default: ``None``) LaTeX symbol to denote the
           complement in the case the latter has to be created; the default
           is built upon the symbol `\setminus`
+        - ``is_open`` -- (default: ``False``) if ``True``, the created subset
+          is assumed to be open with respect to the manifold's topology
 
         OUTPUT:
 
-        - instance of :class:`ManifoldSubset` representing the
-          subset that is difference of ``superset`` minus ``self``
+        - instance of :class:`ManifoldSubset` representing the subset that
+          is ``superset`` minus ``self``
 
         EXAMPLES::
 
@@ -2650,6 +2652,15 @@ def complement(self, superset=None, name=None, latex_name=None, is_open=False):
             ...
             TypeError: superset must be a superset of self
 
+        Demanding that the complement is open makes ``self`` a closed subset::
+
+            sage: A.is_closed()  # False a priori
+            False
+            sage: A.complement(is_open=True)
+            Open subset M_minus_A of the 2-dimensional topological manifold M
+            sage: A.is_closed()
+            True
+
         """
         if superset is None:
             superset = self.manifold()
@@ -2672,11 +2683,13 @@ def difference(self, other, name=None, latex_name=None, is_open=False):
         - ``latex_name`` --  (default: ``None``) LaTeX symbol to denote the
           difference in the case the latter has to be created; the default
           is built upon the symbol `\setminus`
+        - ``is_open`` -- (default: ``False``) if ``True``, the created subset
+          is assumed to be open with respect to the manifold's topology
 
         OUTPUT:
 
-        - instance of :class:`ManifoldSubset` representing the
-          subset that is difference of ``self`` minus ``other``
+        - instance of :class:`ManifoldSubset` representing the subset that is
+          ``self`` minus ``other``
 
         EXAMPLES::
 
@@ -2706,6 +2719,13 @@ def difference(self, other, name=None, latex_name=None, is_open=False):
             sage: M.difference(O, is_open=True)
             Open subset CO2 of the 2-dimensional topological manifold M
 
+        Since `O` is open and we have asked `M\setminus O` to be open, `O`
+        is a clopen set (if `O\neq M` and `O\neq\emptyset`, this implies that
+        `M` is not connected)::
+
+            sage: O.is_closed() and O.is_open()
+            True
+
         """
         # See if it has been created already
         diffs = []