isaacscript-common 2.3.2 → 3.1.1

package/objects/LRoomShapeToRectangles.lua

@@ -4,6 +4,8 @@ local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local ____constants = require("constants")
 local VectorZero = ____constants.VectorZero
 local TWO_BY_TWO_BOTTOM_RIGHT = Vector(25, 13)
+--- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+-- wall would be at "Vector(-1, -1)".)
 ____exports.L_ROOM_SHAPE_TO_RECTANGLES = {
     [RoomShape.LTL] = {
         Vector(13, 0),

package/objects/callbackRegisterFunctions.lua

@@ -73,6 +73,8 @@ local ____postPEffectUpdateReordered = require("callbacks.subscriptions.postPEff
 local postPEffectUpdateReorderedRegister = ____postPEffectUpdateReordered.postPEffectUpdateReorderedRegister
 local ____postPickupCollect = require("callbacks.subscriptions.postPickupCollect")
 local postPickupCollectRegister = ____postPickupCollect.postPickupCollectRegister
+local ____postPickupInitFirst = require("callbacks.subscriptions.postPickupInitFirst")
+local postPickupInitFirstRegister = ____postPickupInitFirst.postPickupInitFirstRegister
 local ____postPickupInitLate = require("callbacks.subscriptions.postPickupInitLate")
 local postPickupInitLateRegister = ____postPickupInitLate.postPickupInitLateRegister
 local ____postPickupStateChanged = require("callbacks.subscriptions.postPickupStateChanged")
@@ -189,6 +191,7 @@ ____exports.CALLBACK_REGISTER_FUNCTIONS = {
     [ModCallbackCustom.POST_NPC_STATE_CHANGED] = postNPCStateChangedRegister,
     [ModCallbackCustom.POST_PEFFECT_UPDATE_REORDERED] = postPEffectUpdateReorderedRegister,
     [ModCallbackCustom.POST_PICKUP_COLLECT] = postPickupCollectRegister,
+    [ModCallbackCustom.POST_PICKUP_INIT_FIRST] = postPickupInitFirstRegister,
     [ModCallbackCustom.POST_PICKUP_INIT_LATE] = postPickupInitLateRegister,
     [ModCallbackCustom.POST_PICKUP_STATE_CHANGED] = postPickupStateChangedRegister,
     [ModCallbackCustom.POST_PIT_RENDER] = postPitRenderRegister,

package/objects/colors.lua

@@ -1,4 +1,8 @@
 local ____exports = {}
+--- A collection of common colors that can be reused.
+-- 
+-- Note that if you want to further modify these colors, you should copy them first with the
+-- `copyColor` function.
 ____exports.COLORS = {
     Black = Color(1, 1, 1),
     Red = Color(1, 0, 0),

package/objects/oppositeDoorSlots.d.ts

@@ -0,0 +1,4 @@
+import { DoorSlot } from "isaac-typescript-definitions";
+export declare const OPPOSITE_DOOR_SLOTS: {
+    readonly [key in DoorSlot]: DoorSlot | undefined;
+};

package/objects/oppositeDoorSlots.lua

@@ -0,0 +1,15 @@
+local ____exports = {}
+local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
+local DoorSlot = ____isaac_2Dtypescript_2Ddefinitions.DoorSlot
+____exports.OPPOSITE_DOOR_SLOTS = {
+    [DoorSlot.NO_DOOR_SLOT] = nil,
+    [DoorSlot.LEFT_0] = DoorSlot.RIGHT_0,
+    [DoorSlot.UP_0] = DoorSlot.DOWN_0,
+    [DoorSlot.RIGHT_0] = DoorSlot.LEFT_0,
+    [DoorSlot.LEFT_1] = DoorSlot.RIGHT_1,
+    [DoorSlot.DOWN_0] = DoorSlot.UP_0,
+    [DoorSlot.UP_1] = DoorSlot.DOWN_1,
+    [DoorSlot.RIGHT_1] = DoorSlot.LEFT_1,
+    [DoorSlot.DOWN_1] = DoorSlot.UP_1
+}
+return ____exports

package/objects/roomShapeBounds.lua

@@ -7,6 +7,8 @@ local NARROW_CONTENTS_WIDTH = ____roomShapeVolumes.NARROW_CONTENTS_WIDTH
 local ONE_BY_ONE_CONTENTS_HEIGHT = ____roomShapeVolumes.ONE_BY_ONE_CONTENTS_HEIGHT
 local ONE_BY_ONE_CONTENTS_WIDTH = ____roomShapeVolumes.ONE_BY_ONE_CONTENTS_WIDTH
 local TWO_BY_TWO_BOUNDS = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
+--- The size of a room shape's contents. This does not include the tiles that the walls are on. L
+-- rooms use the same bounds as a 2x2 room.
 ____exports.ROOM_SHAPE_BOUNDS = {
     [RoomShape.SHAPE_1x1] = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONTENTS_HEIGHT),
     [RoomShape.IH] = Vector(ONE_BY_ONE_CONTENTS_WIDTH, NARROW_CONTENTS_HEIGHT),

package/objects/roomShapeLayoutSizes.lua

@@ -8,6 +8,10 @@ local ONE_BY_ONE_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONT
 local TWO_BY_ONE_VERTICAL_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
 local TWO_BY_ONE_HORIZONTAL_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT)
 local TWO_BY_TWO_LAYOUT_SIZE = Vector(ONE_BY_ONE_CONTENTS_WIDTH * 2, ONE_BY_ONE_CONTENTS_HEIGHT * 2)
+--- The dimensions of a room shape's layout. This is NOT the size of the room's actual contents! For
+-- that, use `ROOM_SHAPE_BOUNDS`.
+-- 
+-- For example, a horizontal narrow room has a layout size of equal to that of a 1x1 room.
 ____exports.ROOM_SHAPE_LAYOUT_SIZES = {
     [RoomShape.SHAPE_1x1] = ONE_BY_ONE_LAYOUT_SIZE,
     [RoomShape.IH] = ONE_BY_ONE_LAYOUT_SIZE,

package/objects/roomShapeToBottomRightPosition.lua

@@ -3,6 +3,8 @@ local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitio
 local RoomShape = ____isaac_2Dtypescript_2Ddefinitions.RoomShape
 local TWO_BY_TWO_BOTTOM_RIGHT_POSITION = Vector(25, 13)
 local ONE_BY_TWO_VERTICAL_BOTTOM_RIGHT_POSITION = Vector(12, 13)
+--- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+-- wall would be at "Vector(-1, -1)".)
 ____exports.ROOM_SHAPE_TO_BOTTOM_RIGHT_POSITION = {
     [RoomShape.SHAPE_1x1] = Vector(12, 6),
     [RoomShape.IH] = Vector(12, 4),

package/objects/roomShapeToDoorSlotsToGridIndexDelta.lua

@@ -11,6 +11,8 @@ local LEFT = -1
 local UP = -LEVEL_GRID_ROW_WIDTH
 local RIGHT = 1
 local DOWN = LEVEL_GRID_ROW_WIDTH
+--- Deltas are considered to be from the safe grid index of the room (i.e. the top left corner, or
+-- top right corner in the case of `RoomShape.LTL`).
 ____exports.ROOM_SHAPE_TO_DOOR_SLOTS_TO_GRID_INDEX_DELTA = {
     [RoomShape.SHAPE_1x1] = __TS__New(Map, {{DoorSlot.LEFT_0, LEFT}, {DoorSlot.UP_0, UP}, {DoorSlot.RIGHT_0, RIGHT}, {DoorSlot.DOWN_0, DOWN}}),
     [RoomShape.IH] = __TS__New(Map, {{DoorSlot.LEFT_0, LEFT}, {DoorSlot.RIGHT_0, RIGHT}}),

package/objects/roomShapeToTopLeftPosition.lua

@@ -5,6 +5,8 @@ local ____constants = require("constants")
 local VectorZero = ____constants.VectorZero
 local NARROW_HORIZONTAL_TOP_LEFT_POSITION = Vector(0, 2)
 local NARROW_VERTICAL_TOP_LEFT_POSITION = Vector(4, 0)
+--- "Vector(0, 0)" corresponds to the top left tile of a room, not including the walls. (The top-left
+-- wall would be at "Vector(-1, -1)".)
 ____exports.ROOM_SHAPE_TO_TOP_LEFT_POSITION = {
     [RoomShape.SHAPE_1x1] = VectorZero,
     [RoomShape.IH] = NARROW_HORIZONTAL_TOP_LEFT_POSITION,

package/objects/roomShapeVolumes.lua

@@ -10,6 +10,9 @@ local NARROW_HORIZONTAL_VOLUME = ____exports.ONE_BY_ONE_CONTENTS_WIDTH * ____exp
 local NARROW_VERTICAL_VOLUME = ____exports.NARROW_CONTENTS_WIDTH * ____exports.ONE_BY_ONE_CONTENTS_HEIGHT
 local ONE_BY_TWO_VOLUME = ONE_BY_ONE_VOLUME * 2
 local L_ROOM_VOLUME = ONE_BY_ONE_VOLUME * 3
+--- Volume is the amount of tiles that are inside the room shape.
+-- 
+-- (This cannot be directly calculated from the bounds since L rooms are a special case.)
 ____exports.ROOM_SHAPE_VOLUMES = {
     [RoomShape.SHAPE_1x1] = ONE_BY_ONE_VOLUME,
     [RoomShape.IH] = NARROW_HORIZONTAL_VOLUME,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isaacscript-common",
-  "version": "2.3.2",
+  "version": "3.1.1",
   "description": "Helper functions and features for IsaacScript mods.",
   "keywords": [
     "isaac",
@@ -22,6 +22,6 @@
   "main": "index",
   "types": "index.d.ts",
   "dependencies": {
-    "isaac-typescript-definitions": "^2.0.54"
+    "isaac-typescript-definitions": "^2.0.55"
   }
 }

package/patchErrorFunctions.lua

@@ -36,6 +36,14 @@ function removeLinesContaining(self, msg, containsMsg)
 end
 LINE_SEPARATOR = "\n"
 USELESS_TRACEBACK_MESSAGES = {"in upvalue 'getTraceback'", "in function 'sandbox.GetTraceback'", "in function 'error'"}
+--- In Lua, the `error` function will tell you the line number of the error, but not give you a full
+-- traceback of the parent functions, which is unlike how JavaScript works. This function monkey
+-- patches the `error` function to add this functionality.
+-- 
+-- Traceback functionality can only be added if the "--luadebug" flag is turned on, so this function
+-- does nothing if the "--luadebug" flag is disabled.
+-- 
+-- @internal
 function ____exports.patchErrorFunction(self)
     if not isLuaDebugEnabled(nil) then
         return

package/sets/bossSets.lua

@@ -37,6 +37,7 @@ local SatanVariant = ____isaac_2Dtypescript_2Ddefinitions.SatanVariant
 local StageType = ____isaac_2Dtypescript_2Ddefinitions.StageType
 local WarVariant = ____isaac_2Dtypescript_2Ddefinitions.WarVariant
 local WidowVariant = ____isaac_2Dtypescript_2Ddefinitions.WidowVariant
+--- Contains just the bosses in Basement (not e.g. Burning Basement).
 local BASEMENT_BOSSES_SET = __TS__New(
     Set,
     {
@@ -56,6 +57,7 @@ local BASEMENT_BOSSES_SET = __TS__New(
         tostring(EntityType.BABY_PLUM) .. ".0"
     }
 )
+--- Contains just the bosses in Cellar (not e.g. Burning Basement).
 local CELLAR_BOSSES_SET = __TS__New(
     Set,
     {
@@ -72,6 +74,7 @@ local CELLAR_BOSSES_SET = __TS__New(
         tostring(EntityType.BABY_PLUM) .. ".0"
     }
 )
+--- Contains just the bosses in Burning Basement (not e.g. Cellar).
 local BURNING_BASEMENT_BOSSES_SET = __TS__New(
     Set,
     {
@@ -92,6 +95,7 @@ local BURNING_BASEMENT_BOSSES_SET = __TS__New(
         tostring(EntityType.BABY_PLUM) .. ".0"
     }
 )
+--- Contains just the bosses in Downpour (not e.g. Burning Basement).
 local DOWNPOUR_BOSSES_SET = __TS__New(
     Set,
     {
@@ -101,6 +105,7 @@ local DOWNPOUR_BOSSES_SET = __TS__New(
         tostring(EntityType.MIN_MIN) .. ".0"
     }
 )
+--- Contains just the bosses in Dross (not e.g. Burning Basement).
 local DROSS_BOSSES_SET = __TS__New(
     Set,
     {
@@ -129,6 +134,7 @@ __TS__SparseArrayPush(
     ____array_0,
     __TS__Spread(DROSS_BOSSES_SET:values())
 )
+--- The set of unique bosses for Basement, Cellar, and so on.
 local ALL_BASEMENT_BOSSES_SET = __TS__New(
     ____Set_1,
     {__TS__SparseArraySpread(____array_0)}
@@ -140,6 +146,7 @@ local BASEMENT_STAGE_TYPE_TO_BOSS_SET_MAP = __TS__New(Map, {
     {StageType.REPENTANCE, DOWNPOUR_BOSSES_SET},
     {StageType.REPENTANCE_B, DROSS_BOSSES_SET}
 })
+--- Contains just the bosses in Caves (not e.g. Flooded Caves).
 local CAVES_BOSSES_SET = __TS__New(
     Set,
     {
@@ -160,6 +167,7 @@ local CAVES_BOSSES_SET = __TS__New(
         tostring(EntityType.BUMBINO) .. ".0"
     }
 )
+--- Contains just the bosses in Catacombs (not e.g. Flooded Caves).
 local CATACOMBS_BOSSES_SET = __TS__New(
     Set,
     {
@@ -181,6 +189,7 @@ local CATACOMBS_BOSSES_SET = __TS__New(
         tostring(EntityType.BUMBINO) .. ".0"
     }
 )
+--- Contains just the bosses in Flooded Caves (not e.g. Catacombs).
 local FLOODED_CAVES_BOSSES_SET = __TS__New(
     Set,
     {
@@ -203,6 +212,7 @@ local FLOODED_CAVES_BOSSES_SET = __TS__New(
         tostring(EntityType.BUMBINO) .. ".0"
     }
 )
+--- Contains just the bosses in Mines (not e.g. Flooded Caves).
 local MINES_BOSSES_SET = __TS__New(
     Set,
     {
@@ -212,6 +222,7 @@ local MINES_BOSSES_SET = __TS__New(
         tostring(EntityType.GIDEON) .. ".0"
     }
 )
+--- Contains just the bosses in Ashpit (not e.g. Flooded Caves).
 local ASHPIT_BOSSES_SET = __TS__New(
     Set,
     {
@@ -240,6 +251,7 @@ __TS__SparseArrayPush(
     ____array_2,
     __TS__Spread(ASHPIT_BOSSES_SET:values())
 )
+--- The set of unique bosses for Caves, Catacombs, and so on.
 local ALL_CAVES_BOSSES_SET = __TS__New(
     ____Set_3,
     {__TS__SparseArraySpread(____array_2)}
@@ -251,6 +263,7 @@ local CAVES_STAGE_TYPE_TO_BOSS_SET_MAP = __TS__New(Map, {
     {StageType.REPENTANCE, MINES_BOSSES_SET},
     {StageType.REPENTANCE_B, ASHPIT_BOSSES_SET}
 })
+--- Contains just the bosses in Depths (not e.g. Dank Depths).
 local DEPTHS_BOSSES_SET = __TS__New(
     Set,
     {
@@ -268,6 +281,7 @@ local DEPTHS_BOSSES_SET = __TS__New(
         tostring(EntityType.REAP_CREEP) .. ".0"
     }
 )
+--- Contains just the bosses in Necropolis (not e.g. Dank Depths).
 local NECROPOLIS_BOSSES_SET = __TS__New(
     Set,
     {
@@ -284,6 +298,7 @@ local NECROPOLIS_BOSSES_SET = __TS__New(
         tostring(EntityType.SISTERS_VIS) .. ".0"
     }
 )
+--- Contains just the bosses in Dank Depths (not e.g. Necropolis).
 local DANK_DEPTHS_BOSSES_SET = __TS__New(
     Set,
     {
@@ -301,6 +316,7 @@ local DANK_DEPTHS_BOSSES_SET = __TS__New(
         tostring(EntityType.REAP_CREEP) .. ".0"
     }
 )
+--- Contains just the bosses in Mausoleum (not e.g. Dank Depths).
 local MAUSOLEUM_BOSSES_SET = __TS__New(
     Set,
     {
@@ -309,6 +325,7 @@ local MAUSOLEUM_BOSSES_SET = __TS__New(
         tostring(EntityType.HERETIC) .. ".0"
     }
 )
+--- Contains just the bosses in Gehenna (not e.g. Dank Depths).
 local GEHENNA_BOSSES_SET = __TS__New(
     Set,
     {
@@ -335,6 +352,7 @@ __TS__SparseArrayPush(
     ____array_4,
     __TS__Spread(GEHENNA_BOSSES_SET:values())
 )
+--- The set of unique bosses for Depths, Necropolis, and so on.
 local ALL_DEPTHS_BOSSES_SET = __TS__New(
     ____Set_5,
     {__TS__SparseArraySpread(____array_4)}
@@ -346,6 +364,7 @@ local DEPTHS_STAGE_TYPE_TO_BOSS_SET_MAP = __TS__New(Map, {
     {StageType.REPENTANCE, MAUSOLEUM_BOSSES_SET},
     {StageType.REPENTANCE_B, GEHENNA_BOSSES_SET}
 })
+--- Contains just the bosses in Womb (not e.g. Scarred Womb).
 local WOMB_BOSSES_SET = __TS__New(
     Set,
     {
@@ -363,6 +382,7 @@ local WOMB_BOSSES_SET = __TS__New(
         tostring(EntityType.MATRIARCH) .. ".0"
     }
 )
+--- Contains just the bosses in Utero (not e.g. Scarred Womb).
 local UTERO_BOSSES_SET = __TS__New(
     Set,
     {
@@ -379,6 +399,7 @@ local UTERO_BOSSES_SET = __TS__New(
         tostring(EntityType.HEADLESS_HORSEMAN) .. ".0"
     }
 )
+--- Contains just the bosses in Scarred Womb (not e.g. Utero).
 local SCARRED_WOMB_BOSSES_SET = __TS__New(
     Set,
     {
@@ -397,6 +418,7 @@ local SCARRED_WOMB_BOSSES_SET = __TS__New(
         tostring(EntityType.MATRIARCH) .. ".0"
     }
 )
+--- Contains just the bosses in Corpse (not e.g. Scarred Womb).
 local CORPSE_BOSSES_SET = __TS__New(
     Set,
     {
@@ -424,6 +446,7 @@ __TS__SparseArrayPush(
     ____array_6,
     __TS__Spread(GEHENNA_BOSSES_SET:values())
 )
+--- The set of unique bosses for Depths, Necropolis, and so on.
 local ALL_WOMB_BOSSES_SET = __TS__New(
     ____Set_7,
     {__TS__SparseArraySpread(____array_6)}

package/sets/charactersWithNoRedHeartsSet.lua

@@ -4,6 +4,8 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+--- The set of characters where red heart containers will be turned into soul hearts (e.g. Blue
+-- Baby). This includes The Lost and Tainted Lost. This does not include Keeper or Tainted Keeper.
 ____exports.CHARACTERS_WITH_NO_RED_HEARTS_SET = __TS__New(Set, {
     PlayerType.BLUE_BABY,
     PlayerType.THE_LOST,

package/sets/charactersWithNoSoulHeartsSet.lua

@@ -4,6 +4,8 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+--- The set of characters where soul hearts will be automatically stripped away (e.g. Bethany). This
+-- includes The Lost and Tainted Lost.
 ____exports.CHARACTERS_WITH_NO_SOUL_HEARTS_SET = __TS__New(Set, {
     PlayerType.THE_LOST,
     PlayerType.KEEPER,

package/sets/lostStyleCharactersSet.lua

@@ -4,6 +4,8 @@ local __TS__New = ____lualib.__TS__New
 local ____exports = {}
 local ____isaac_2Dtypescript_2Ddefinitions = require("isaac-typescript-definitions")
 local PlayerType = ____isaac_2Dtypescript_2Ddefinitions.PlayerType
+--- This is the set of characters that look like The Lost and play the "LostDeath" animation when
+-- they die.
 ____exports.LOST_STYLE_CHARACTERS_SET = __TS__New(Set, {
     PlayerType.THE_LOST,
     PlayerType.THE_SOUL,

package/types/AnyEntity.d.ts

@@ -1,2 +1,12 @@
 /// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
+/// <reference types="isaac-typescript-definitions" />
 export declare type AnyEntity = Entity | EntityBomb | EntityEffect | EntityFamiliar | EntityKnife | EntityLaser | EntityNPC | EntityPickup | EntityPlayer | EntityProjectile | EntityTear;

package/types/PickingUpItem.lua

@@ -7,20 +7,27 @@ local CollectibleType = ____isaac_2Dtypescript_2Ddefinitions.CollectibleType
 local ItemType = ____isaac_2Dtypescript_2Ddefinitions.ItemType
 local DEFAULT_ITEM_TYPE = ItemType.NULL
 local DEFAULT_SUB_TYPE = CollectibleType.NULL
+---
+-- @internal
 function ____exports.newPickingUpItem(self)
     return {itemType = DEFAULT_ITEM_TYPE, subType = DEFAULT_SUB_TYPE}
 end
+---
+-- @internal
 function ____exports.resetPickingUpItem(self, pickingUpItem)
     pickingUpItem.itemType = DEFAULT_ITEM_TYPE
     pickingUpItem.subType = DEFAULT_SUB_TYPE
 end
 local COLLECTIBLE_ITEM_TYPES = __TS__New(Set, {ItemType.PASSIVE, ItemType.ACTIVE, ItemType.FAMILIAR})
+--- Helper function to narrow the type of `PickingUpItem`.
 function ____exports.pickingUpItemIsNull(self, pickingUpItem)
     return pickingUpItem.itemType == ItemType.NULL
 end
+--- Helper function to narrow the type of `PickingUpItem`.
 function ____exports.pickingUpItemIsCollectible(self, pickingUpItem)
     return COLLECTIBLE_ITEM_TYPES:has(pickingUpItem.itemType)
 end
+--- Helper function to narrow the type of `PickingUpItem`.
 function ____exports.pickingUpItemIsTrinket(self, pickingUpItem)
     return pickingUpItem.itemType == ItemType.TRINKET
 end

package/upgradeMod.d.ts

@@ -1,8 +1,8 @@
 /// <reference types="isaac-typescript-definitions" />
 import { ModUpgraded } from "./classes/ModUpgraded";
 /**
- * Use this function to enable the custom callbacks and other optional features provided by
- * `isaacscript-common`.
+ * Use this function to enable the {@link ModCallbackCustom custom callbacks} and other optional
+ * features provided by `isaacscript-common`.
  *
  * For example:
  *
@@ -10,10 +10,10 @@ import { ModUpgraded } from "./classes/ModUpgraded";
  * const modVanilla = RegisterMod("My Mod", 1);
  * const mod = upgradeMod(modVanilla);
  *
- * // Subscribe to vanilla callbacks
+ * // Subscribe to vanilla callbacks.
  * mod.AddCallback(ModCallback.POST_UPDATE, postUpdate);
  *
- * // Subscribe to custom callbacks
+ * // Subscribe to custom callbacks.
  * mod.AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup);
  * ```
  *

package/upgradeMod.lua

@@ -17,6 +17,24 @@ local initFeaturesMajor = ____initFeatures.initFeaturesMajor
 local initFeaturesMinor = ____initFeatures.initFeaturesMinor
 local ____patchErrorFunctions = require("patchErrorFunctions")
 local patchErrorFunction = ____patchErrorFunctions.patchErrorFunction
+--- Use this function to enable the {@link ModCallbackCustomcustom callbacks} and other optional
+-- features provided by `isaacscript-common`.
+-- 
+-- For example:
+-- 
+-- ```ts
+-- const modVanilla = RegisterMod("My Mod", 1);
+-- const mod = upgradeMod(modVanilla);
+-- 
+-- // Subscribe to vanilla callbacks.
+-- mod.AddCallback(ModCallback.POST_UPDATE, postUpdate);
+-- 
+-- // Subscribe to custom callbacks.
+-- mod.AddCallbackCustom(ModCallbackCustom.POST_ITEM_PICKUP, postItemPickup);
+-- ```
+-- 
+-- @param modVanilla The mod object returned by the `RegisterMod` function.
+-- @returns The upgraded mod object.
 function ____exports.upgradeMod(self, modVanilla)
     patchErrorFunction(nil)
     local mod = __TS__New(ModUpgraded, modVanilla)