Document `Target_ShouldReleaseLockOn` [Target Docs 8/8] (#2135)

* target range and leash docs

* format

1 files changed, 27 insertions, 10 deletions

diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 78710229f..c74f29f50 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -1629,29 +1629,46 @@ TargetRangeParams sTargetRanges[TARGET_MODE_MAX] = {
 };
 
 /**
- * Checks if an actor at distance `distSq` is inside the range specified by its targetMode
+ * Checks if an actor at `distSq` is inside the range specified by its `targetMode`.
+ *
+ * Note that this gets used for both the target range check and for the lock-on leash range check.
+ * Despite how the data is presented in `sTargetRanges`, the leash range is stored as a scale factor value.
+ * When checking the leash range, this scale factor is applied to the input distance and checked against
+ * the base `rangeSq` value, which was used to initiate the lock-on in the first place.
  */
 u32 Target_ActorIsInRange(Actor* actor, f32 distSq) {
     return distSq < sTargetRanges[actor->targetMode].rangeSq;
 }
 
-s32 func_8002F0C8(Actor* actor, Player* player, s32 flag) {
+/**
+ * Returns true if an actor lock-on should be released.
+ * This function does not actually release the lock-on, as that is Player's responsibility.
+ *
+ * If an actor's update function is NULL or `ACTOR_FLAG_0` is unset, the lock-on should be released.
+ *
+ * There is also a check for Player exceeding the lock-on leash distance.
+ * Note that this check will be ignored if `ignoreLeash` is true.
+ *
+ */
+s32 Target_ShouldReleaseLockOn(Actor* actor, Player* player, s32 ignoreLeash) {
     if ((actor->update == NULL) || !(actor->flags & ACTOR_FLAG_0)) {
         return true;
     }
 
-    if (!flag) {
-        s16 var = (s16)(actor->yawTowardsPlayer - 0x8000) - player->actor.shape.rot.y;
-        s16 abs_var = ABS(var);
-        f32 dist;
+    if (!ignoreLeash) {
+        s16 yawDiff = (s16)(actor->yawTowardsPlayer - 0x8000) - player->actor.shape.rot.y;
+        s16 yawDiffAbs = ABS(yawDiff);
+        f32 distSq;
 
-        if ((player->focusActor == NULL) && (abs_var > 0x2AAA)) {
-            dist = MAXFLOAT;
+        if ((player->focusActor == NULL) && (yawDiffAbs > 0x2AAA)) {
+            // This function is only called (and is only relevant) when `player->focusActor != NULL`.
+            // This is unreachable.
+            distSq = MAXFLOAT;
         } else {
-            dist = actor->xyzDistToPlayerSq;
+            distSq = actor->xyzDistToPlayerSq;
         }
 
-        return !Target_ActorIsInRange(actor, sTargetRanges[actor->targetMode].leashScale * dist);
+        return !Target_ActorIsInRange(actor, sTargetRanges[actor->targetMode].leashScale * distSq);
     }
 
     return false;