types: fix missing/incorrect jsdocs

src/aabb_c.js

@@ -11,6 +11,10 @@ import * as b2Math from './include/math_functions_h.js';
  * @namespace Aabb
  */
 
+/**
+ * @import {b2AABB} from './include/math_functions_h.js'
+ */
+
 // Get surface area of an AABB (the perimeter length)
 export function b2Perimeter(a)
 {

src/block_array_c.js

@@ -43,6 +43,7 @@ export class b2ContactArray
 {
     constructor(capacity = 0)
     {
+        /** @type {b2ContactSim[]} */
         this.data = [];
         this.count = 0;
         this.capacity = capacity;

src/body_c.js

@@ -28,6 +28,11 @@ import { b2MassData } from './include/collision_h.js';
  * @namespace Body
  */
 
+/**
+ * @import {b2WorldId} from './include/id_h.js'
+ * @import {b2BodyDef, b2ContactData} from './include/types_h.js'
+ */
+
 export function b2MakeSweep(bodySim, out)
 {
     out.c1.x = bodySim.center0X;

src/debug_draw.js

@@ -520,13 +520,18 @@ export function CreateDebugDraw(canvas, ctx, scale = 20.0)
     return draw;
 }
 
+/**
+ * @callback RAFCallback
+ * @param {number} deltaTime - Time elapsed since last frame in seconds, capped at 0.1s
+ * @param {number} totalTime - Total accumulated time in seconds
+ * @param {number} currentFps - Current frames per second, updated once per second
+ * @returns {void}
+ */
+
 /**
  * @function RAF
  * @summary Implements a requestAnimationFrame loop with timing and FPS tracking
- * @param {function} callback - Function to call each frame with signature (deltaTime, totalTime, currentFps)
- * @param {number} callback.deltaTime - Time elapsed since last frame in seconds, capped at 0.1s
- * @param {number} callback.totalTime - Total accumulated time in seconds
- * @param {number} callback.currentFps - Current frames per second, updated once per second
+ * @param {RAFCallback} callback - Function to call each frame with signature (deltaTime, totalTime, currentFps)
  * @description
  * Creates an animation loop using requestAnimationFrame that tracks timing information
  * and FPS. The callback is invoked each frame with the time delta, total time, and
@@ -593,7 +598,7 @@ function loadPNGImage(imageUrl)
  * Attach a graphic image to a physics body
  * @function AttachImage
  * @param {number} worldId - The ID of the Box2D world
- * @param {number} bodyId - The ID of the body to attach the image to
+ * @param {b2BodyId} bodyId - The ID of the body to attach the image to
  * @param {string} path - Directory path where the image is located
  * @param {string} imgName - Name of the image file
  * @param {b2Vec2} [drawOffset=null] - Offset vector for drawing the image

src/distance_c.js

@@ -52,6 +52,10 @@ import { b2_linearSlop } from './include/core_h.js';
  * @namespace Distance
  */
 
+/**
+ * @import {b2ShapeCastPairInput, b2TOIInput} from './include/collision_h'
+ */
+
 /**
  * @function b2GetSweepTransform
  * @summary Computes an interpolated transform at a specified time during a sweep motion.

src/distance_joint_c.js

@@ -31,6 +31,10 @@ import { b2MakeSoft } from './include/solver_h.js';
 
 /**
  * @namespace DistanceJoint
+*/
+
+/**
+ * @import {b2JointId} from './include/id_h'
  */
 
 /**

src/dynamic_tree_c.js

@@ -18,6 +18,11 @@ import { b2TreeNode } from './include/collision_h.js';
  * @namespace DynamicTree
  */
 
+/**
+ * @import {b2AABB, b2Vec2} from './include/math_functions_h.js'
+ * @import {b2RayCastInput, b2ShapeCastInput} from './include/collision_h.js'
+ */
+
 const B2_TREE_STACK_SIZE = 1024;
 
 function b2IsLeaf(node)

src/geometry_c.js

@@ -44,6 +44,10 @@ import { b2ValidateHull } from './include/hull_h.js';
  * @namespace Geometry
  */
 
+/**
+ * @import {b2Hull, b2RayCastInput, b2Segment, b2ShapeCastInput} from './include/collision_h.js'
+ */
+
 /**
  * Validates a ray cast input structure.
  * @function b2IsValidRay
@@ -537,7 +541,7 @@ export function b2ComputePolygonMass(shape, density)
  * @function b2ComputeCircleAABB
  * @summary Computes an Axis-Aligned Bounding Box (AABB) for a circle shape after applying a transform.
  * @param {b2Circle} shape - The circle shape containing center point and radius.
- * @param {b2Transform} xf2 - The transform to be applied, consisting of a position (p) and rotation (q).
+ * @param {b2Transform} xf - The transform to be applied, consisting of a position (p) and rotation (q).
  * @returns {b2AABB} An AABB object defined by minimum and maximum points that bound the transformed circle.
  * @description
  * Calculates the AABB by transforming the circle's center point using the provided transform
@@ -559,7 +563,7 @@ export function b2ComputeCircleAABB(shape, xf)
  * @function b2ComputeCapsuleAABB
  * @summary Computes an Axis-Aligned Bounding Box (AABB) for a capsule shape.
  * @param {b2Capsule} shape - A capsule shape defined by two centers and a radius.
- * @param {b2Transform} xf2 - A transform containing position and rotation to be applied to the capsule.
+ * @param {b2Transform} xf - A transform containing position and rotation to be applied to the capsule.
  * @returns {b2AABB} An AABB that encompasses the transformed capsule shape.
  * @description
  * Calculates the minimum and maximum bounds of a capsule after applying a transform.
@@ -587,7 +591,7 @@ export function b2ComputeCapsuleAABB(shape, xf)
  * Computes the Axis-Aligned Bounding Box (AABB) for a polygon shape after applying a transform.
  * The AABB includes the polygon's radius in its calculations.
  * @param {b2Polygon} shape - The polygon shape containing vertices and radius
- * @param {b2Transform} xf2 - The transform to apply, consisting of position (p) and rotation (q)
+ * @param {b2Transform} xf - The transform to apply, consisting of position (p) and rotation (q)
  * @returns {b2AABB} An AABB object with lower and upper bounds that encompass the transformed polygon
  */
 export function b2ComputePolygonAABB(shape, xf)
@@ -634,7 +638,7 @@ export function b2ComputePolygonAABB(shape, xf)
  * @summary Computes an Axis-Aligned Bounding Box (AABB) for a line segment.
  * @function b2ComputeSegmentAABB
  * @param {b2Segment} shape - A line segment defined by two points (point1 and point2)
- * @param {b2Transform} xf2 - A transform containing position and rotation to be applied to the segment
+ * @param {b2Transform} xf - A transform containing position and rotation to be applied to the segment
  * @returns {b2AABB} An AABB that contains the transformed line segment
  * @description
  * Transforms the segment's endpoints using the provided transform, then creates an AABB

src/hull_c.js

@@ -15,6 +15,10 @@ import { b2_linearSlop } from './include/core_h.js';
  * @namespace Hull
  */
 
+/**
+ * @import {b2Vec2} from './include/math_functions_h.js'
+ */
+
 // quickhull recursion
 function b2RecurseHull(p1, p2, ps, count)
 {

src/include/collision_h.js

@@ -649,3 +649,11 @@ export class b2TreeNode
         this.enlarged = false;
     }
 }
+
+
+/**
+ * These are performance results returned by dynamic tree queries.
+ * @typedef {Object} b2TreeStats
+ * @property {number} nodeVisits - Number of internal nodes visited during the query.
+ * @property {number} leafVisits - Number of leaf nodes visited during the query.
+ */

src/include/core_h.js

@@ -55,8 +55,6 @@ export function B2_ARRAY_COUNT(A)
 /**
  * @summary Sets custom memory allocator functions for Box2D (Not supported in Phaser Box2D JS)
  * @function b2SetAllocator
- * @param {Function} allocFcn - Memory allocation function pointer
- * @param {Function} freeFcn - Memory deallocation function pointer
  * @returns {void}
  * @description
  * This function is intended to set custom memory allocation and deallocation functions
@@ -72,7 +70,7 @@ export function b2SetAllocator()
 /**
  * @summary Returns the byte count for Box2D memory usage.
  * @function b2GetByteCount
- * @returns {number} An integer representing the total bytes used by Box2D.
+ * @returns {void}
  * @description
  * This function is a stub that warns users that byte count tracking is not
  * supported in the JavaScript implementation of Box2D for Phaser.
@@ -85,7 +83,7 @@ export function b2GetByteCount()
 /**
  * @summary Creates a timer object for performance measurement.
  * @function b2CreateTimer
- * @returns {b2Timer} A timer object for measuring elapsed time.
+ * @returns {void} A timer object for measuring elapsed time.
  * @description
  * This function creates a timer object but is not supported in the Phaser Box2D JS implementation.
  * When called, it issues a console warning about lack of support.
@@ -98,7 +96,7 @@ export function b2CreateTimer()
 /**
  * @summary Gets system ticks for timing purposes
  * @function b2GetTicks
- * @returns {number} Returns 0 since this function not supported
+ * @returns {void} Returns 0 since this function not supported
  * @description
  * This is a stub function that exists for compatibility with Box2D but is not
  * implemented in the Phaser Box2D JS port. It logs a warning when called.
@@ -112,7 +110,7 @@ export function b2GetTicks()
 /**
  * @summary Gets the elapsed time in milliseconds.
  * @function b2GetMilliseconds
- * @returns {number} The elapsed time in milliseconds.
+ * @returns {void} The elapsed time in milliseconds.
  * @description
  * This function is a stub that warns that millisecond timing is not supported
  * in the Phaser Box2D JS implementation.
@@ -126,15 +124,14 @@ export function b2GetMilliseconds()
 /**
  * @summary Gets elapsed milliseconds from a b2Timer and resets it.
  * @function b2GetMillisecondsAndReset
- * @param {b2Timer} timer - The Box2D timer object to query and reset
- * @returns {number} The elapsed time in milliseconds
+ * @returns {void} The elapsed time in milliseconds
  * @description
  * This function returns the elapsed milliseconds from a Box2D timer object and resets it.
  * In the JavaScript implementation for Phaser Box2D, this functionality is not supported
  * and will trigger a warning.
  * @throws {Warning} Logs a console warning that this function is not supported
  */
-export function b2GetMillisecondsAndReset(timer)
+export function b2GetMillisecondsAndReset()
 {
     console.warn("b2GetMillisecondsAndReset not supported");
 }

src/include/math_functions_h.js

@@ -635,8 +635,8 @@ function b2Distance(a, b)
 /**
  * @function b2DistanceSquared
  * @summary Calculates the squared distance between two 2D points.
- * @param {b2Vec2} a - The first 2D vector point
- * @param {b2Vec2} b - The second 2D vector point
+ * @param {b2Vec2 | {x: number, y: number}} a - The first 2D vector point
+ * @param {b2Vec2 | {x: number, y: number}} b - The second 2D vector point
  * @returns {number} The squared distance between points a and b
  * @description
  * Computes the squared Euclidean distance between two points without taking the square root.

src/include/types_h.js

@@ -691,6 +691,87 @@ export class b2ContactData
     }
 }
 
+/**
+ * Prototype for a contact filter callback.
+ * This is called when a contact pair is considered for collision. This allows you to
+ * perform custom logic to prevent collision between shapes. This is only called if
+ * one of the two shapes has custom filtering enabled.
+ *
+ * **Notes:**
+ * - This function must be thread-safe.
+ * - This is only called if one of the two shapes has enabled custom filtering.
+ * - This is called only for awake dynamic bodies.
+ *
+ * @warning Do not attempt to modify the world inside this callback.
+ * @see b2ShapeDef
+ * @ingroup world
+ * @callback b2CustomFilterFcn
+ * @param {b2ShapeId} shapeIdA - The first shape ID.
+ * @param {b2ShapeId} shapeIdB - The second shape ID.
+ * @param {any} context - User-defined context.
+ * @returns {boolean} False to disable the collision.
+ */
+
+/**
+ * Prototype for a pre-solve callback.
+ * This is called after a contact is updated. This allows you to inspect a
+ * contact before it goes to the solver. If you are careful, you can modify the
+ * contact manifold (e.g., modify the normal).
+ *
+ * **Notes:**
+ * - This function must be thread-safe.
+ * - This is only called if the shape has enabled pre-solve events.
+ * - This is called only for awake dynamic bodies.
+ * - This is not called for sensors.
+ * - The supplied manifold has impulse values from the previous step.
+ *
+ * @warning Do not attempt to modify the world inside this callback.
+ * @ingroup world
+ * @callback b2PreSolveFcn
+ * @param {b2ShapeId} shapeIdA - The first shape ID.
+ * @param {b2ShapeId} shapeIdB - The second shape ID.
+ * @param {b2Manifold} manifold - The contact manifold.
+ * @param {any} context - User-defined context.
+ * @returns {boolean} False to disable the contact this step.
+ */
+
+/**
+ * Prototype callback for overlap queries.
+ * Called for each shape found in the query.
+ *
+ * @see b2World_OverlapABB
+ * @ingroup world
+ * @callback b2OverlapResultFcn
+ * @param {b2ShapeId} shapeId - The shape ID found in the query.
+ * @param {any} context - User-defined context.
+ * @returns {boolean} False to terminate the query.
+ */
+
+/**
+ * Prototype callback for ray casts.
+ * Called for each shape found in the query. You control how the ray cast proceeds by returning a float:
+ *
+ * - `-1`: Ignore this shape and continue.
+ * - `0`: Terminate the ray cast.
+ * - `fraction`: Clip the ray to this point.
+ * - `1`: Don't clip the ray and continue.
+ *
+ * @see b2World_CastRay
+ * @ingroup world
+ * @callback b2CastResultFcn
+ * @param {b2ShapeId} shapeId - The shape hit by the ray.
+ * @param {b2Vec2} point - The point of initial intersection.
+ * @param {b2Vec2} normal - The normal vector at the point of intersection.
+ * @param {number} fraction - The fraction along the ray at the point of intersection.
+ * @param {any} context - User-defined context.
+ * @returns {number} - `-1` to filter, `0` to terminate, `fraction` to clip the ray for closest hit, `1` to continue.
+ */
+
+
+/// These colors are used for debug draw and mostly match the named SVG colors.
+/// See https://www.rapidtables.com/web/color/index.html
+/// https://johndecember.com/html/spec/colorsvg.html
+/// https://upload.wikimedia.org/wikipedia/commons/2/2b/SVG_Recognized_color_keyword_names.svg
 export const b2HexColor = {
     b2_colorAliceBlue: 0xf0f8ff,
     b2_colorAntiqueWhite: 0xfaebd7,

src/include/world_h.js

@@ -5,6 +5,10 @@
  * - Copyright 2024 Phaser Studio Inc, released under the MIT license.
  */
 
+/**
+ * @import {b2WorldId} from './id_h.js'
+ */
+
 export const b2_maxWorkers = 1;
 
 export {
@@ -29,13 +33,12 @@ export {
  * @summary Gets the performance profile data for a Box2D world.
  * @function b2World_GetProfile
  * @param {b2WorldId} worldId - The identifier of the Box2D world.
- * @returns {b2Profile} A profile object containing performance metrics.
+ * @returns {void} A profile object containing performance metrics.
  * @description
  * This function returns performance profiling data for a Box2D world.
  * Not supported in Phaser Box2D JS implementation.
- * @throws {Error} Outputs a console warning indicating lack of support in Phaser Box2D JS.
  */
-export function b2World_GetProfile()
+export function b2World_GetProfile(worldId)
 {
     console.warn("b2World_GetProfile not supported");
 }
@@ -44,12 +47,12 @@ export function b2World_GetProfile()
  * Gets the current counters from a Box2D world instance.
  * @function b2World_GetCounters
  * @param {b2WorldId} worldId - The ID of the Box2D world instance.
- * @returns {b2Counters} An object containing various Box2D performance counters.
+ * @returns {void} An object containing various Box2D performance counters.
  * @description
  * This function is not supported in the Phaser Box2D JS implementation and will
  * generate a console warning when called.
  */
-export function b2World_GetCounters()
+export function b2World_GetCounters(worldId)
 {
     console.warn("b2World_GetCounters not supported");
 }
@@ -63,7 +66,7 @@ export function b2World_GetCounters()
  * This function is a stub that displays a warning message indicating that memory statistics
  * dumping is not supported in the Phaser Box2D JavaScript implementation.
  */
-export function b2World_DumpMemoryStats()
+export function b2World_DumpMemoryStats(worldId)
 {
     console.warn("b2World_DumpMemoryStats not supported");
 }

src/joint_c.js

@@ -36,6 +36,10 @@ import { b2JointId } from "./include/id_h.js";
  * @namespace Joint
  */
 
+/**
+ * @import {b2WorldId, b2BodyId} from './include/id_h.js'
+ */
+
 /**
  * Creates a default distance joint definition with preset values.
  * @function b2DefaultDistanceJointDef