From 97a02d87951e64580fa9df6b45ef89fba5e34dc6 Mon Sep 17 00:00:00 2001
From: vocx-fc <ecabreracs@gmail.com>
Date: Wed, 7 Aug 2019 23:56:45 -0500
Subject: [PATCH] Draft: WorkingPlane, Pythonic style, improved the docstrings;
 alignToSelection() only really works with Faces because it calls
 alignToFace(); it doesn't work with Edges nor Wires because alignToCurve()
 isn't fully implemented.

---
 src/Mod/Draft/WorkingPlane.py | 62 +++++++++++++++++++++++++++++++++--
 1 file changed, 60 insertions(+), 2 deletions(-)

diff --git a/src/Mod/Draft/WorkingPlane.py b/src/Mod/Draft/WorkingPlane.py
index 1cec8226b7f1..38ccae257f15 100644
--- a/src/Mod/Draft/WorkingPlane.py
+++ b/src/Mod/Draft/WorkingPlane.py
@@ -549,13 +549,71 @@ def alignToFace(self, shape, offset=0):
             return False
 
     def alignTo3Points(self, p1, p2, p3, offset=0):
+        """Align the plane to three points.
+
+        It makes a closed quadrilateral face with the three points,
+        and then calls `alignToFace(shape, offset)`.
+
+        Parameter
+        ---------
+        p1 : Base::Vector3
+            The first point.
+        p2 : Base::Vector3
+            The second point.
+        p3 : Base::Vector3
+            The third point.
+
+        offset : float
+            Defaults to zero. A value which will be used to offset
+            the plane in the direction of its `axis`.
+
+        Returns
+        -------
+        bool
+            `True` if the operation was succesful, and `False` otherwise.
+        """
         import Part
         w = Part.makePolygon([p1, p2, p3, p1])
         f = Part.Face(w)
         return self.alignToFace(f, offset)
 
-    def alignToSelection(self, offset):
-        '''If selection uniquely defines a plane, align working plane to it.  Return success (bool)'''
+    def alignToSelection(self, offset=0):
+        """Align the plane to a selection if it defines a plane.
+
+        If the selection uniquely defines a plane it will be used.
+        Currently it only works with one object selected, a `'Face'`.
+        It extracts the shape of the object or subobject
+        and then calls `alignToFace(shape, offset)`.
+
+        Parameter
+        ---------
+        offset : float
+            Defaults to zero. A value which will be used to offset
+            the plane in the direction of its `axis`.
+
+        Returns
+        -------
+        bool
+            `True` if the operation was succesful, and `False` otherwise.
+            It returns `False` if the selection has no elements,
+            or if it has more than one element,
+            or if the object is not derived from `'Part::Feature'`
+            or if the object doesn't have a `Shape`.
+
+        To do
+        -----
+        The method returns `False` if the selection list has more than
+        one element.
+        The method should search the list for objects like faces, points,
+        edges, wires, etc., and call the appropriate aligning submethod.
+
+        The method could work for curves (`'Edge'`  or `'Wire'`) but
+        `alignToCurve()` isn't fully implemented.
+
+        See also
+        --------
+        alignToFace, alignToCurve
+        """
         import FreeCADGui
         sex = FreeCADGui.Selection.getSelectionEx(FreeCAD.ActiveDocument.Name)
         if len(sex) == 0: