isaacscript-common 2.3.1 → 3.1.0

package/classes/DefaultMap.lua

@@ -4,58 +4,106 @@ local Map = ____lualib.Map
 local __TS__ClassExtends = ____lualib.__TS__ClassExtends
 local __TS__TypeOf = ____lualib.__TS__TypeOf
 local ____exports = {}
-local parseArguments, parseArgumentsOne, parseArgumentsTwo, parseDefaultValueOrDefaultValueFactory
-function parseArguments(self, firstArg, secondArg)
-    return secondArg == nil and parseArgumentsOne(nil, firstArg) or parseArgumentsTwo(nil, firstArg, secondArg)
-end
-function parseArgumentsOne(self, firstArg)
-    local arg = firstArg
-    local ____parseDefaultValueOrDefaultValueFactory_result_1 = parseDefaultValueOrDefaultValueFactory(nil, arg)
-    local defaultValue = ____parseDefaultValueOrDefaultValueFactory_result_1.defaultValue
-    local defaultValueFactory = ____parseDefaultValueOrDefaultValueFactory_result_1.defaultValueFactory
-    return {iterable = nil, defaultValue = defaultValue, defaultValueFactory = defaultValueFactory}
-end
-function parseArgumentsTwo(self, firstArg, secondArg)
-    local firstArgType = type(firstArg)
-    if firstArgType ~= "table" then
-        error("A DefaultMap constructor with two arguments must have the first argument be the initializer list.")
-    end
-    local ____parseDefaultValueOrDefaultValueFactory_result_2 = parseDefaultValueOrDefaultValueFactory(nil, secondArg)
-    local defaultValue = ____parseDefaultValueOrDefaultValueFactory_result_2.defaultValue
-    local defaultValueFactory = ____parseDefaultValueOrDefaultValueFactory_result_2.defaultValueFactory
-    return {iterable = firstArg, defaultValue = defaultValue, defaultValueFactory = defaultValueFactory}
-end
-function parseDefaultValueOrDefaultValueFactory(self, arg)
-    if type(arg) == "function" then
-        return {defaultValue = nil, defaultValueFactory = arg}
-    end
-    if type(arg) == "boolean" or type(arg) == "number" or type(arg) == "string" then
-        return {defaultValue = arg, defaultValueFactory = nil}
-    end
-    return error("A DefaultMap was instantiated with an unknown type of: " .. __TS__TypeOf(arg))
-end
+--- `DefaultMap` is a data structure that makes working with default values easier.
+-- 
+-- It is a common pattern to look up a value in a `Map`, and then, if the value does not exist, set
+-- a default value for the key, and then return the default value. `DefaultMap` abstracts this
+-- operation away by providing the `getAndSetDefault` method.
+-- 
+-- Using a `DefaultMap` is nice because it makes code more declarative, since you specify what the
+-- default value is alongside the types of the keys/values.
+-- 
+-- When instantiating a new `DefaultMap`, you must specify default value as the first argument. (The
+-- default value is the initial value that will be assigned to every new entry in the
+-- `getAndSetDefault` method.) For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value of "foo".
+-- const defaultMapWithString = new DefaultMap<string, string>("foo");
+-- 
+-- const value = defaultMapWithString.getAndSetDefault("bar");
+-- // value is now "foo" and an entry for "bar" is now set.
+-- ```
+-- 
+-- Sometimes, instead of having a static initial value for every entry in the map, you will want a
+-- dynamic initial value that is contingent upon the key or some other variable. In these cases, you
+-- can instead specify that the `DefaultMap` should run a function that will return the initial
+-- value. (This is referred to as a "factory function".) For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value based on "someGlobalVariable".
+-- const factoryFunction = () => someGlobalVariable ? 0 : 1;
+-- const defaultMapWithFactoryFunction = new DefaultMap<string, string>(factoryFunction);
+-- ```
+-- 
+-- Note that in TypeScript and Lua, booleans, numbers, and strings are "passed by value". This means
+-- that when the `DefaultMap` creates a new entry, if the default value is one of these 3 types, the
+-- values will be copied. On the other hand, arrays and maps and other complex data structures are
+-- "passed by reference". This means that when the `DefaultMap` creates a new entry, if the default
+-- value is an array, then it would not be copied. Instead, the same shared array would be assigned
+-- to every entry. Thus, to solve this problem, any variable that is passed by reference must be
+-- created using a factory function to ensure that each copy is unique. For example:
+-- 
+-- ```ts
+-- // Initializes a new empty DefaultMap with a default value of a new empty array.
+-- const factoryFunction = () => [] as ;
+-- const defaultMapWithArray = new DefaultMap<string, string[]>(factoryFunction);
+-- ```
+-- 
+-- In the previous two examples, the factory functions did not have any arguments. But you can also
+-- specify a factory function that takes one or more arguments:
+-- 
+-- ```ts
+-- const factoryFunction = (arg: boolean) => arg ? 0 : 1;
+-- const defaultMapWithArg = new DefaultMap<string, string, [arg: boolean]>(factoryFunction);
+-- ```
+-- 
+-- Similar to a normal `Map`, you can also include an initializer list in the constructor as the
+-- second argument:
+-- 
+-- ```ts
+-- // Initializes a DefaultMap with a default value of "foo" and some initial values.
+-- const defaultMapWithInitialValues = new DefaultMap<string, string>("foo", [
+--   ["a1", "a2"],
+--   ["b1", "b2"],
+-- ], );
+-- ```
+-- 
+-- Finally, note that `DefaultMap` has the following additional utility methods:
+-- 
+-- - `getAndSetDefault` - The method that is called inside the overridden `get` method. In most
+--   cases, you can use the overridden `get` method instead of calling this function directly.
+--   However, if a factory function was provided during instantiation, and the factory function has
+--   one or more arguments, then you must call this method instead (and provide the corresponding
+--   arguments).
+-- - `getWithoutDefault` - Calls the original `Map.get` function (without setting the default
+--   value).
+-- - `getDefaultValue` - Returns the default value to be used for a new key. (If a factory function
+--   was provided during instantiation, this will execute the factory function.)
+-- - `getConstructorArg` - Helper method for cloning the map. Returns either the default value or
+--   the reference to the factory function.
 ____exports.DefaultMap = __TS__Class()
 local DefaultMap = ____exports.DefaultMap
 DefaultMap.name = "DefaultMap"
 __TS__ClassExtends(DefaultMap, Map)
-function DefaultMap.prototype.____constructor(self, iterableOrDefaultValueOrDefaultValueFactory, defaultValueOrDefaultValueFactory)
-    local ____parseArguments_result_0 = parseArguments(nil, iterableOrDefaultValueOrDefaultValueFactory, defaultValueOrDefaultValueFactory)
-    local iterable = ____parseArguments_result_0.iterable
-    local defaultValue = ____parseArguments_result_0.defaultValue
-    local defaultValueFactory = ____parseArguments_result_0.defaultValueFactory
-    if defaultValue == nil and defaultValueFactory == nil then
-        error("A DefaultMap must be instantiated with either a default value or a function that returns a default value.")
+function DefaultMap.prototype.____constructor(self, defaultValueOrFactoryFunction, initializerArray)
+    local argType = __TS__TypeOf(defaultValueOrFactoryFunction)
+    local argIsPrimitive = argType == "boolean" or argType == "number" or argType == "string"
+    local argIsFunction = argType == "function"
+    if not argIsPrimitive and not argIsFunction then
+        error(("Failed to instantiate a DefaultMap since the provided default value was of type \"" .. argType) .. "\". This error usually means that you are trying to use an array (or some other non-primitive data structure that is passed by reference) as the default value. Instead, return the data structure in a factory function, like \"() => []\". See the DefaultMap documentation for more details.")
     end
-    if iterable == nil then
-        Map.prototype.____constructor(self)
+    Map.prototype.____constructor(self, initializerArray)
+    if argIsFunction then
+        self.defaultValue = nil
+        self.defaultValueFactory = defaultValueOrFactoryFunction
     else
-        Map.prototype.____constructor(self, iterable)
+        self.defaultValue = defaultValueOrFactoryFunction
+        self.defaultValueFactory = nil
     end
-    self.defaultValue = defaultValue
-    self.defaultValueFactory = defaultValueFactory
 end
 function DefaultMap.prototype.getAndSetDefault(self, key, ...)
-    local value = self:get(key)
+    local value = Map.prototype.get(self, key)
     if value ~= nil then
         return value
     end
@@ -63,6 +111,9 @@ function DefaultMap.prototype.getAndSetDefault(self, key, ...)
     self:set(key, defaultValue)
     return defaultValue
 end
+function DefaultMap.prototype.getWithoutDefault(self, key)
+    return Map.prototype.get(self, key)
+end
 function DefaultMap.prototype.getDefaultValue(self, ...)
     if self.defaultValue ~= nil then
         return self.defaultValue

package/classes/ModUpgraded.d.ts

@@ -2,9 +2,9 @@ import { ModCallback } from "isaac-typescript-definitions";
 import { ModCallbackCustom } from "../enums/ModCallbackCustom";
 import { AddCallbackParameterCustom } from "../interfaces/AddCallbackParameterCustom";
 /**
- * `isaacscript-common` has many custom callbacks that you can use in your mods. Instead of
- * hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to use, which
- * extends the base class and adds a new method of `AddCallbackCustom`.
+ * `isaacscript-common` has many {@link ModCallbackCustom custom callbacks} that you can use in your
+ * mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
+ * use, which extends the base class and adds a new method of `AddCallbackCustom`.
  *
  * To upgrade your mod, use the `upgradeMod` helper function.
  */

package/classes/ModUpgraded.lua

@@ -3,6 +3,11 @@ local __TS__Class = ____lualib.__TS__Class
 local ____exports = {}
 local ____callbackRegisterFunctions = require("objects.callbackRegisterFunctions")
 local CALLBACK_REGISTER_FUNCTIONS = ____callbackRegisterFunctions.CALLBACK_REGISTER_FUNCTIONS
+--- `isaacscript-common` has many {@link ModCallbackCustomcustom callbacks} that you can use in your
+-- mods. Instead of hijacking the vanilla `Mod` object, we provide a `ModUpgraded` object for you to
+-- use, which extends the base class and adds a new method of `AddCallbackCustom`.
+-- 
+-- To upgrade your mod, use the `upgradeMod` helper function.
 ____exports.ModUpgraded = __TS__Class()
 local ModUpgraded = ____exports.ModUpgraded
 ModUpgraded.name = "ModUpgraded"

package/constants.lua

@@ -8,38 +8,79 @@ local TrinketSlot = ____isaac_2Dtypescript_2Ddefinitions.TrinketSlot
 local ____enums = require("functions.enums")
 local getEnumLength = ____enums.getEnumLength
 local getLastEnumValue = ____enums.getLastEnumValue
+--- The distance of the laser when Azazel does not have any range up items yet. For more info, see
+-- the documentation for the `getAzazelBrimstoneDistance` function.
 ____exports.AZAZEL_DEFAULT_BRIMSTONE_DISTANCE = 75.125
+--- The path to the png file for collectible items during Curse of the Blind, making them appear with
+-- a red question mark.
 ____exports.BLIND_ITEM_PNG_PATH = "gfx/items/collectibles/questionmark.png"
+--- Bombs explode when their frame count is equal to this value.
 ____exports.BOMB_EXPLODE_FRAME = 45
 ____exports.DEFAULT_ITEM_POOL_TYPE = ItemPoolType.TREASURE
+--- This is also the distance that a player spawns from the door that they enter a room from.
 ____exports.DISTANCE_OF_GRID_TILE = 40
 ____exports.DOOR_HITBOX_RADIUS = 11
+--- When Eggies take fatal damage, they go into NpcState.STATE_SUICIDE and spawn 14 Swarm Spiders
+-- while their StateFrame ticks upwards. The 14th spider appears when the StateFrame is at this
+-- value.
 ____exports.EGGY_STATE_FRAME_OF_FINAL_SPIDER = 45
+--- A non-existent or completely transparent PNG file for use in clearing sprites. For more
+-- information, see the documentation for the `clearSprite` helper function.
 ____exports.EMPTY_PNG_PATH = "gfx/none.png"
+--- The random items that appear when the player has TMTRAINER are generated on the fly as they are
+-- encountered by the player. The first TMTRAINER item takes the final possible 32 bit number. The
+-- second TMTRAINER item subtracts one from that, and so on.
 ____exports.FIRST_GLITCHED_COLLECTIBLE_TYPE = (1 << 32) - 1
 ____exports.GAME_FRAMES_PER_SECOND = 30
 ____exports.GRID_INDEX_CENTER_OF_1X1_ROOM = 67
 ____exports.ISAAC_FRAMES_PER_SECOND = 60
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first column is
+-- represented by grid indexes 0, 13, 26, and so on.
 ____exports.LEVEL_GRID_COLUMN_HEIGHT = 13
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+-- by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+-- on.
 ____exports.LEVEL_GRID_ROW_WIDTH = 13
+--- The floor is represented by a 13x13 grid. Room indexes start at 0. The first row is represented
+-- by grid indexes from 0 to 12. The second row is represented by grid indexes from 13 to 25, and so
+-- on. The maximum room index possible is 168. (It is not 169 because we start at 0 instead of 1.)
 ____exports.MAX_LEVEL_GRID_INDEX = 168
+--- The game has a limit on the number of currently spawned familiars and will refuse to spawn any
+-- more if it reaches the limit. Blue flies and blue spiders have a lower priority and will be
+-- deleted to make room for other familiars.
 ____exports.MAX_NUM_FAMILIARS = 64
+--- The game can only handle up to four different players.
 ____exports.MAX_NUM_INPUTS = 4
+--- With Birthright, it is possible for Magdalene to have 18 heart containers.
 ____exports.MAX_PLAYER_HEART_CONTAINERS = 18
+--- As the player continues to move in a direction, they will accelerate. When going from one wall to
+-- another in a 2x2 room at 2.0 speed (the maximum that the speed stat can rise to), the amount of
+-- units moved per update frame will climb to around 9.797 as they hit the opposite wall. The
+-- constant specifies a value of 9.8 to be safe.
 ____exports.MAX_PLAYER_SPEED_IN_UNITS = 9.8
 ____exports.MAX_PLAYER_TRINKET_SLOTS = getEnumLength(nil, TrinketSlot)
 ____exports.FIRST_ROOM_TYPE = RoomType.DEFAULT
 ____exports.LAST_ROOM_TYPE = getLastEnumValue(nil, RoomType)
+--- The maximum speed stat that a player can have. Any additional speed beyond this will not take
+-- effect.
 ____exports.MAX_SPEED_STAT = 2
 ____exports.FIRST_STAGE = LevelStage.BASEMENT_1
 ____exports.LAST_STAGE = getLastEnumValue(nil, LevelStage)
+--- Corresponds to the maximum value for `EntityPlayer.SamsonBerserkCharge`.
 ____exports.MAX_TAINTED_SAMSON_BERSERK_CHARGE = 100000
 ____exports.NUM_DIMENSIONS = getEnumLength(nil, Dimension) - 1
 ____exports.SECOND_IN_MILLISECONDS = 1000
 ____exports.MINUTE_IN_MILLISECONDS = 60 * ____exports.SECOND_IN_MILLISECONDS
 ____exports.ONE_BY_ONE_ROOM_GRID_SIZE = 135
+--- After taking damage, `EntityPlayer.SamsonBerserkCharge` is incremented by this amount.
 ____exports.TAINTED_SAMSON_BERSERK_CHARGE_FROM_TAKING_DAMAGE = 10000
+--- This is the number of draw coordinates that each heart spans on the UI in the upper left hand
+-- corner.
 ____exports.UI_HEART_WIDTH = 12
+--- This is a safer version of the `Vector.One` constant. (Other mods can mutate this `Vector.One`,
+-- so it is not safe to use.)
 ____exports.VectorOne = Vector(1, 1)
+--- This is a safer version of the `Vector.Zero` constant. (Other mods can mutate `Vector.Zero`
+-- vector, so it is not safe to use.)
 ____exports.VectorZero = Vector(0, 0)
 return ____exports

package/constantsFirstLast.lua

@@ -11,40 +11,103 @@ local itemConfig = ____cachedClasses.itemConfig
 local ____enums = require("functions.enums")
 local getEnumLength = ____enums.getEnumLength
 local getLastEnumValue = ____enums.getLastEnumValue
+--- Equal to `CollectibleType.SAD_ONION`.
 ____exports.FIRST_COLLECTIBLE_TYPE = CollectibleType.SAD_ONION
+--- Will change depending on how many modded collectibles there are.
+-- 
+-- Equal to `itemConfig.GetCollectibles().Size - 1`. (`Size` includes invalid collectibles. We
+-- subtract one to account for `CollectibleType.NULL`.)
 ____exports.LAST_COLLECTIBLE_TYPE = itemConfig:GetCollectibles().Size - 1
+--- Calculated from the `CollectibleType` enum.
+-- 
+-- Note that this cannot be calculated from the length of the enum, because unlike all of the other
+-- enums, collectible types are not contiguous.
 ____exports.LAST_VANILLA_COLLECTIBLE_TYPE = getLastEnumValue(nil, CollectibleType)
+--- If there are no modded collectibles, this constant will represent a collectible type that does
+-- not exist.
 ____exports.FIRST_MODDED_COLLECTIBLE_TYPE = ____exports.LAST_VANILLA_COLLECTIBLE_TYPE + 1
+--- Calculated from the `CollectibleType` enum. `CollectibleType.NULL` is not included.
 ____exports.NUM_VANILLA_COLLECTIBLE_TYPES = getEnumLength(nil, CollectibleType) - 1
+--- Unlike vanilla collectible types, modded collectible types are always contiguous.
 ____exports.NUM_MODDED_COLLECTIBLE_TYPES = ____exports.LAST_COLLECTIBLE_TYPE - ____exports.LAST_VANILLA_COLLECTIBLE_TYPE
 ____exports.NUM_COLLECTIBLE_TYPES = ____exports.NUM_VANILLA_COLLECTIBLE_TYPES + ____exports.NUM_MODDED_COLLECTIBLE_TYPES
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetTrinkets().Size - 1`. (We subtract one to account for
+-- `TrinketType.NULL`.)
 ____exports.NUM_TRINKET_TYPES = itemConfig:GetTrinkets().Size - 1
+--- Calculated from the `TrinketType` enum. `TrinketType.NULL` is not included.
 ____exports.NUM_VANILLA_TRINKET_TYPES = getEnumLength(nil, TrinketType) - 1
 ____exports.NUM_MODDED_TRINKET_TYPES = ____exports.NUM_TRINKET_TYPES - ____exports.NUM_VANILLA_TRINKET_TYPES
+--- Equal to `TrinketType.SWALLOWED_PENNY`.
 ____exports.FIRST_TRINKET_TYPE = TrinketType.SWALLOWED_PENNY
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetTrinkets().Size - 1`. (We subtract one to account for
+-- `TrinketType.NULL`.)
 ____exports.LAST_TRINKET_TYPE = ____exports.NUM_TRINKET_TYPES
+--- Calculated from the `TrinketType` enum.
 ____exports.LAST_VANILLA_TRINKET_TYPE = getLastEnumValue(nil, TrinketType)
+--- If there are no modded trinkets, this constant will represent a trinket type that does not exist.
 ____exports.FIRST_MODDED_TRINKET_TYPE = ____exports.LAST_VANILLA_TRINKET_TYPE + 1
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetCards().Size - 1`. (We subtract one to account for `Card.NULL`.)
 ____exports.NUM_CARDS = itemConfig:GetCards().Size - 1
+--- Calculated from the `Card` enum. `Card.NULL` is not included.
 ____exports.NUM_VANILLA_CARDS = getEnumLength(nil, Card) - 1
 ____exports.NUM_MODDED_CARDS = ____exports.NUM_CARDS - ____exports.NUM_VANILLA_CARDS
+--- Equal to `Card.FOOL`.
 ____exports.FIRST_CARD = Card.FOOL
+--- Will change depending on how many modded cards there are.
+-- 
+-- Equal to `itemConfig.GetCards().Size - 1`. (We subtract one to account for `Card.NULL`.)
 ____exports.LAST_CARD = ____exports.NUM_CARDS
+--- Calculated from the `Card` enum.
 ____exports.MAX_VANILLA_CARD = getLastEnumValue(nil, Card)
+--- If there are no modded cards, this constant will represent a card that does not exist.
 ____exports.FIRST_MODDED_CARD = ____exports.MAX_VANILLA_CARD + 1
+--- Will change depending on how many modded pill effects there are.
+-- 
+-- Equal to `itemConfig.GetPillEffects().Size - 1`. (We subtract one to account for
+-- `PillEffect.NULL`.)
 ____exports.NUM_PILL_EFFECTS = itemConfig:GetPillEffects().Size - 1
+--- Calculated from the `PillEffect` enum.
+-- 
+-- (There is no `PillEffect.NULL` in the custom enum, so we don't have to subtract one here.)
 ____exports.NUM_VANILLA_PILL_EFFECTS = getEnumLength(nil, PillEffect)
 ____exports.NUM_MODDED_PILL_EFFECTS = ____exports.NUM_PILL_EFFECTS - ____exports.NUM_VANILLA_PILL_EFFECTS
+--- Equal to `PillEffect.BAD_GAS`.
 ____exports.FIRST_PILL_EFFECT = PillEffect.BAD_GAS
+--- Will change depending on how many modded pill effects there are.
+-- 
+-- Equal to `itemConfig.GetPillEffects().Size - 1`. (We subtract one to account for
+-- `PillEffect.NULL`.)
 ____exports.LAST_PILL_EFFECT = ____exports.NUM_PILL_EFFECTS
+--- Calculated from the `PillEffect` enum.
 ____exports.LAST_VANILLA_PILL_EFFECT = getLastEnumValue(nil, PillEffect)
+--- If there are no modded pill effects, this constant will represent a pill effect that does not
+-- exist.
 ____exports.FIRST_MODDED_PILL_EFFECT = ____exports.LAST_VANILLA_PILL_EFFECT + 1
+--- Equal to `PillColor.BLUE_BLUE`.
 ____exports.FIRST_PILL_COLOR = PillColor.BLUE_BLUE
+--- Equal to `PillColor.WHITE_YELLOW`.
+-- 
+-- Note that `PillColor.GOLD` is technically higher, but that is not considered for the purposes of
+-- this constant.
 ____exports.LAST_NORMAL_PILL_COLOR = PillColor.WHITE_YELLOW
+--- Equal to `PillColor.HORSE_BLUE_BLUE`.
 ____exports.FIRST_HORSE_PILL_COLOR = PillColor.HORSE_BLUE_BLUE
+--- Equal to `PillColor.HORSE_WHITE_YELLOW`.
+-- 
+-- Note that `PillColor.HORSE_GOLD` is technically higher, but that is not considered for the
+-- purposes of this constant.
 ____exports.LAST_HORSE_PILL_COLOR = PillColor.HORSE_WHITE_YELLOW
 ____exports.NUM_NORMAL_PILL_COLORS = ____exports.LAST_NORMAL_PILL_COLOR - ____exports.FIRST_PILL_COLOR
+--- Equal to `PlayerType.ISAAC`.
 ____exports.FIRST_CHARACTER = PlayerType.ISAAC
+--- Calculated from the `PlayerType` enum.
 ____exports.LAST_VANILLA_CHARACTER = getLastEnumValue(nil, PlayerType)
+--- If there are no modded characters, this constant will represent a character that does not exist.
 ____exports.FIRST_MODDED_CHARACTER = ____exports.LAST_VANILLA_CHARACTER + 1
 return ____exports

package/enums/HealthType.lua

@@ -1,4 +1,7 @@
 local ____exports = {}
+--- This represents the type of health that is either given or taken away from a player. Note that we
+-- cannot use the `HeartSubType` enum for this purpose this since it has no value for broken hearts
+-- or max hearts.
 ____exports.HealthType = {}
 ____exports.HealthType.RED = 0
 ____exports.HealthType[____exports.HealthType.RED] = "RED"

package/enums/ModCallbackCustom.d.ts

@@ -2,7 +2,7 @@
  * - The Isaac API offers a lot of callbacks, but a lot of times there isn't one for the specific
  *   thing that you are looking to do. So, `isaacscript-common` adds a bunch of new callbacks that
  *   you can use.
- * - The extra callbacks are efficient such that no code is ran until they have one or more
+ * - The extra callbacks are efficient such that no code is executed until there is one or more
  *   subscriptions.
  * - You must upgrade your mod with the `upgradeMod` helper function before using a custom callback.
  */

package/enums/ModCallbackCustom.lua

@@ -1,4 +1,10 @@
 local ____exports = {}
+--- - The Isaac API offers a lot of callbacks, but a lot of times there isn't one for the specific
+--   thing that you are looking to do. So, `isaacscript-common` adds a bunch of new callbacks that
+--   you can use.
+-- - The extra callbacks are efficient such that no code is executed until there is one or more
+--   subscriptions.
+-- - You must upgrade your mod with the `upgradeMod` helper function before using a custom callback.
 ____exports.ModCallbackCustom = {}
 ____exports.ModCallbackCustom.POST_BOMB_INIT_LATE = 0
 ____exports.ModCallbackCustom[____exports.ModCallbackCustom.POST_BOMB_INIT_LATE] = "POST_BOMB_INIT_LATE"

package/enums/private/CopyableIsaacAPIClassType.lua

@@ -1,4 +1,5 @@
 local ____exports = {}
+--- This must match the enumeration in the JSDoc comments for `deepCopy` and `merge`.
 ____exports.CopyableIsaacAPIClassType = {}
 ____exports.CopyableIsaacAPIClassType.COLOR = "Color"
 ____exports.CopyableIsaacAPIClassType.K_COLOR = "KColor"

package/enums/private/SerializationBrand.lua

@@ -1,4 +1,9 @@
 local ____exports = {}
+--- During serialization, we write an arbitrary string key to the object with a value of an empty
+-- string. This is used during deserialization to instantiate the correct type of object.
+-- 
+-- Note that we do not bother branding TSTL classes because we have no way to invoke the proper
+-- constructor during deserialization.
 ____exports.SerializationBrand = {}
 ____exports.SerializationBrand.DEFAULT_MAP = "__TSTL_DEFAULT_MAP"
 ____exports.SerializationBrand.MAP = "__TSTL_MAP"

package/features/characterHealthConversion.lua

@@ -74,10 +74,16 @@ function prePickupCollisionHeart(self, pickup, collider)
 end
 local FEATURE_NAME = "character health manager"
 characterHealthReplacementMap = __TS__New(Map)
+---
+-- @internal
 function ____exports.characterHealthConversionInit(self, mod)
     mod:AddCallback(ModCallback.POST_PEFFECT_UPDATE, postPEffectUpdate)
     mod:AddCallback(ModCallback.PRE_PICKUP_COLLISION, prePickupCollisionHeart, PickupVariant.HEART)
 end
+--- Helper function to make a character that has the same health mechanic as Blue Baby (red heart
+-- containers --> soul hearts) or Dark Judas (red heart containers --> black hearts).
+-- 
+-- Call this function once at the beginning of your mod to declare the health conversion type.
 function ____exports.registerCharacterHealthConversion(self, playerType, conversionHeartSubType)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     characterHealthReplacementMap:set(playerType, conversionHeartSubType)

package/features/characterStats.lua

@@ -27,9 +27,26 @@ function evaluateCache(self, player, cacheFlag)
 end
 local FEATURE_NAME = "character stat manager"
 charactersStatMap = __TS__New(Map)
+---
+-- @internal
 function ____exports.characterStatsInit(self, mod)
     mod:AddCallback(ModCallback.EVALUATE_CACHE, evaluateCache)
 end
+--- Helper function to manage the stats for a vanilla or custom character. Call this function once at
+-- the beginning of your mod to declare the starting stats.
+-- 
+-- You must provide this function with a map of CacheFlag to the default stat amount. For example,
+-- the default amount of damage is 3.5. To make a custom character start with 4.5 damage:
+-- 
+-- ```ts
+-- const fooDefaultStats = new Map<CacheFlag, number>([
+--   [CacheFlag.DAMAGE, 4.5],
+-- ])
+-- registerCharacterStats(PlayerTypeCustom.FOO, fooDefaultStats);
+-- ```
+-- 
+-- Note that the format for the `CacheFlag.FIRE_DELAY` value should be in the tears stat format, not
+-- the `MaxFireDelay` format.
 function ____exports.registerCharacterStats(self, playerType, statMap)
     errorIfFeaturesNotInitialized(nil, FEATURE_NAME)
     charactersStatMap:set(playerType, statMap)

package/features/debugDisplay/exports.d.ts

@@ -1,4 +1,21 @@
 /// <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" />
+/// <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" />
 /**
  * After using the "playerDisplay" console command, text will be drawn on each player for debugging
  * purposes. Use this function to specify a callback function that will returns the string that