Merge pull request #2492 from firedrakeproject/connorjward/functionsp…

…ace-docfixes

WithGeometry doc fixes

docs/source/mesh-coordinates.rst

@@ -92,7 +92,7 @@ functions over to the new mesh.  To move `f` over to ``mesh``, use:
 
 .. code-block:: python3
 
-   g = Function(functionspaceimpl.WithGeometry(f.function_space(), mesh),
+   g = Function(functionspaceimpl.WithGeometry.create(f.function_space(), mesh),
                 val=f.topological)
 
 This creates a :py:class:`~.Function` `g` which shares data with `f`,

firedrake/functionspaceimpl.py

@@ -29,9 +29,16 @@ class WithGeometry(ufl.FunctionSpace):
     Users should not instantiate a :class:`WithGeometry` object
     explicitly except in a small number of cases.
 
-    :arg function_space: The topological function space to attach
-        geometry to.
+    When instantiating a :class:`WithGeometry`, users should call
+    :func:`create` rather than :func:`__init__`.
+
     :arg mesh: The mesh with geometric information to use.
+    :arg element: The UFL element.
+    :arg component: The component of this space in a parent vector
+        element space, or ``None``.
+    :arg cargo: :class:`FunctionSpaceCargo` instance carrying
+        Firedrake-specific data that is not required for code
+        generation.
     """
     def __init__(self, mesh, element, component=None, cargo=None):
         assert component is None or isinstance(component, int)
@@ -43,6 +50,12 @@ def __init__(self, mesh, element, component=None, cargo=None):
 
     @classmethod
     def create(cls, function_space, mesh):
+        """Create a :class:`WithGeometry`.
+
+        :arg function_space: The topological function space to attach
+            geometry to.
+        :arg mesh: The mesh with geometric information to use.
+        """
         function_space = function_space.topological
         assert mesh.topology is function_space.mesh()
         assert mesh.topology is not mesh