Draft: WorkingPlane, Pythonic style, improved the docstrings; moved the description of the points within the parameter section

src/Mod/Draft/WorkingPlane.py

@@ -1121,17 +1121,9 @@ class plane:
 def getPlacementFromPoints(points):
     """Return a placement from a list of 3 or 4 points.
 
-    With these points a temporary plane is defined.
-    The first point is the plane's `position`.
-    The other two points are used to define the `u` and `v` axes,
-    as originating from the first point.
+    With these points a temporary `plane` is defined.
 
-    If the fourth point exists, it is used to define the plane's `axis`
-    as originating from the first point.
-    If no fourth point is provided, the cross product bewtween the previously
-    defined `u` and `v` is used as `axis`.
-
-    Then it returns the `Base::Placement` returned from `getPlacement()`.
+    Then it returns the `Base::Placement` returned from `plane.getPlacement()`.
 
     Parameters
     ----------
@@ -1139,11 +1131,25 @@ def getPlacementFromPoints(points):
         A list with 3 or 4 points to create a temporary plane
         from which to extract the placement.
 
+        The first point is the plane's `position`.
+        The other two points are used to define the `u` and `v` axes,
+        as originating from the first point.
+
+        If the fourth point exists, it is used to define the plane's `axis`
+        as originating from the first point.
+        If no fourth point is provided, the cross product bewtween
+        the previously defined `u` and `v` is used as `axis`.
+
     Return
     ------
     Base::Placement
         A placement obtained from the temporary plane
-        defined by the points.
+        defined by `points`,
+        or `None` is it fails to use the points.
+
+    See also
+    --------
+    getPlacement
     """
     pl = plane()
     try:
@@ -1162,7 +1168,33 @@ def getPlacementFromPoints(points):
 
 
 def getPlacementFromFace(face, rotated=False):
-    "returns a placement from a face"
+    """Return a placement from a face.
+
+    It creates a temporary `plane` and uses `alignToFace(face)`
+    to set its orientation.
+
+    Then it returns the `Base::Placement` returned
+    from `plane.getPlacement(rotated)`.
+
+    Parameter
+    ---------
+    face : Part.Face
+        A shape of type `'Face'`.
+    rotated : bool, optional
+        It defaults to `False`. If it is `True`, the temporary plane
+        switches `axis` with `-v` to produce a rotated placement.
+
+    Returns
+    -------
+    Base::Placement
+        A placement obtained from the temporary plane
+        defined by `face`,
+        or `None` if it fails to use `face`.
+
+    See also
+    --------
+    alignToFace, getPlacement
+    """
     pl = plane()
     try:
         pl.alignToFace(face)