From a64ac95016803f24a01a21ada42e786148d79d90 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Teodor=20K=C3=A4llman?=
 <94024065+RedPhoenixQ@users.noreply.github.com>
Date: Fri, 4 Oct 2024 00:44:06 +0200
Subject: [PATCH] Add docs for group property on bodies (#82)

* docs: add documentation for groups

Refs: #80

* docs: don't overwrite docs for group in bodies

Having a doc comment on the getter will have priority over the docs
provided in the BodyOptions interface
---
 src/bodies/circle.ts  |  4 +---
 src/bodies/polygon.ts |  4 +---
 src/model.ts          | 14 ++++++++++++++
 src/utils.ts          | 30 ++++++++++++++++++++++++++++++
 4 files changed, 46 insertions(+), 6 deletions(-)

diff --git a/src/bodies/circle.ts b/src/bodies/circle.ts
index 58629494..a5494a0c 100644
--- a/src/bodies/circle.ts
+++ b/src/bodies/circle.ts
@@ -192,9 +192,7 @@ export class Circle extends SATCircle implements BBox, BodyProps {
     return this.scale;
   }
 
-  /**
-   * group for collision filtering
-   */
+  // Don't overwrite docs from BodyProps
   get group(): number {
     return this._group;
   }
diff --git a/src/bodies/polygon.ts b/src/bodies/polygon.ts
index 253460f3..12d51083 100644
--- a/src/bodies/polygon.ts
+++ b/src/bodies/polygon.ts
@@ -229,9 +229,7 @@ export class Polygon extends SATPolygon implements BBox, BodyProps {
     this.setScale(scale);
   }
 
-  /**
-   * group for collision filtering
-   */
+  // Don't overwrite docs from BodyProps
   get group(): number {
     return this._group;
   }
diff --git a/src/model.ts b/src/model.ts
index 13e09682..5a1146ec 100644
--- a/src/model.ts
+++ b/src/model.ts
@@ -16,6 +16,9 @@ import { Polygon } from "./bodies/polygon";
 // version 4.0.0 1=1 copy
 import RBush from "./external/rbush";
 
+// Import type for documentation linking
+import type { canInteract } from "./utils";
+
 export {
   Polygon as DecompPolygon,
   Point as DecompPoint,
@@ -109,6 +112,17 @@ export interface BodyOptions {
 
   /**
    * group for collision filtering
+   *
+   * Based on {@link https://box2d.org/documentation/md_simulation.html#filtering Box2D}
+   * ({@link https://aurelienribon.wordpress.com/2011/07/01/box2d-tutorial-collision-filtering/ tutorial})
+   *
+   * Values in {@link BodyGroup} are predefined and used each the body type and
+   * should not be used for custom filtering
+   *
+   * `0b00000001 << 16` to `0b01000000 << 16` (max 0x7fffffff) are free to use for custom groups
+   *
+   * @see {@link canInteract} for how groups are used
+   * @default 0x7fffffff // member of all groups (can interact with everyting)
    */
   group?: number;
 }
diff --git a/src/utils.ts b/src/utils.ts
index 10640c2f..b077590c 100644
--- a/src/utils.ts
+++ b/src/utils.ts
@@ -173,6 +173,7 @@ export function extendBody(body: Body, options: BodyOptions = {}): void {
   body.isStatic = !!options.isStatic;
   body.isTrigger = !!options.isTrigger;
   body.padding = options.padding || 0;
+  // Default value should be reflected in documentation of `BodyOptions.group`
   body.group = options.group ?? 0x7fffffff;
 
   if (body.typeGroup !== BodyGroup.Circle && options.isCentered) {
@@ -217,8 +218,37 @@ export function intersectAABB(bodyA: BBox, bodyB: BBox): boolean {
 /**
  * checks if two bodies can interact (for collision filtering)
  *
+ * Based on {@link https://box2d.org/documentation/md_simulation.html#filtering Box2D}
+ * ({@link https://aurelienribon.wordpress.com/2011/07/01/box2d-tutorial-collision-filtering/ tutorial})
+ *
  * @param bodyA
  * @param bodyB
+ *
+ * @example
+ * const body1 = { group: 0b00000000_00000000_00000001_00000000 }
+ * const body2 = { group: 0b11111111_11111111_00000011_00000000 }
+ * const body3 = { group: 0b00000010_00000000_00000100_00000000 }
+ *
+ * // Body 1 has the first custom group but cannot interact with any other groups
+ * // except itself because the first 16 bits are all zeros, only bodies with an
+ * // identical value can interact with it.
+ * canInteract(body1, body1) // returns true (identical groups can always interact)
+ * canInteract(body1, body2) // returns false
+ * canInteract(body1, body3) // returns false
+ *
+ * // Body 2 has the first and second group and can interact with all other
+ * // groups, but only if that body also can interact with is custom group.
+ * canInteract(body2, body1) // returns false (body1 cannot interact with others)
+ * canInteract(body2, body2) // returns true (identical groups can always interact)
+ * canInteract(body2, body3) // returns true
+ *
+ * // Body 3 has the third group but can interact with the second group.
+ * // This means that Body 2 and Body 3 can interact with each other but no other
+ * // body can interact with Body 1 because it doesn't allow interactions with
+ * // any other custom group.
+ * canInteract(body3, body1) // returns false (body1 cannot interact with others)
+ * canInteract(body3, body2) // returns true
+ * canInteract(body3, body3) // returns true (identical groups can always interact)
  */
 export function canInteract(
   { group: groupA }: Body,