From 4b3cb142eae6be91c7f30c7b836bcfeca584bacf Mon Sep 17 00:00:00 2001
From: Russell Johnson <47639332+Russ4262@users.noreply.github.com>
Date: Tue, 17 Aug 2021 21:22:52 -0500
Subject: [PATCH] Path: Add docString and comments for `getAllIncludedFaces()`
 method

---
 src/Mod/Path/PathScripts/PathMillFace.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/src/Mod/Path/PathScripts/PathMillFace.py b/src/Mod/Path/PathScripts/PathMillFace.py
index 2f1928b553..2fd245b768 100644
--- a/src/Mod/Path/PathScripts/PathMillFace.py
+++ b/src/Mod/Path/PathScripts/PathMillFace.py
@@ -257,6 +257,8 @@ class ObjectFace(PathPocketBase.ObjectPocket):
         return False
 
     def getAllIncludedFaces(self, base, env, faceZ):
+        '''getAllIncludedFaces(base, env, faceZ)...
+        Return all `base` faces extending above `faceZ` whose boundboxes overlap with the `env` boundbox.'''
         included = []
 
         eXMin = env.BoundBox.XMin
@@ -272,6 +274,7 @@ class ObjectFace(PathPocketBase.ObjectPocket):
             return False
 
         for fi in range(0, len(base.Shape.Faces)):
+            # Check all faces of `base` shape
             incl = False
             face = base.Shape.Faces[fi]
             fXMin = face.BoundBox.XMin
@@ -281,8 +284,9 @@ class ObjectFace(PathPocketBase.ObjectPocket):
             fZMax = face.BoundBox.ZMax
 
             if fZMax > eZMin:
-                if isOverlap(fXMin, fXMax, eXMin, eXMax):
-                    if isOverlap(fYMin, fYMax, eYMin, eYMax):
+                # Include face if its boundbox overlaps envelope boundbox
+                if isOverlap(fXMin, fXMax, eXMin, eXMax):  # check X values
+                    if isOverlap(fYMin, fYMax, eYMin, eYMax):  # check Y values
                         incl = True
             if incl:
                 included.append(face)