added some documentation

src/playercards/AllCardsBag.ttslua

@@ -131,6 +131,7 @@ function addCardToIndex(cardData)
   end
 end
 
+-- Creates the supplemental indexes for classes, weaknesses etc.
 function buildSupplementalIndexes()
   for cardId, card in pairs(cardIdIndex) do
     local cardMetadata = card.metadata
@@ -213,6 +214,7 @@ function cardComparator(id1, id2)
   end
 end
 
+---@return boolean: If true, the bag is currently not indexing and ready to be accessed
 function isIndexReady()
   if not indexingDone then
     broadcastToAll("Still loading player cards, please try again in a few seconds", {0.9, 0.2, 0.2})
@@ -221,25 +223,24 @@ function isIndexReady()
 end
 
 -- Returns a specific card from the bag, based on ArkhamDB ID
--- Params table:
---     id: String ID of the card to retrieve
--- Return: If the indexes are still being constructed, an empty table is
---     returned. Otherwise, a single table with the following fields
---       cardData: TTS object data, suitable for spawning the card
---       cardMetadata: Table of parsed metadata
-function getCardById(params)
+---@param id string ID of the card to retrieve
+---@return table: If the indexes are still being constructed, returns an empty table.
+--  Otherwise, a single table with the following fields
+--    cardData: TTS object data, suitable for spawning the card
+--    cardMetadata: Table of parsed metadata
+function getCardById(id)
   if not isIndexReady() then return {} end
-  return cardIdIndex[params.id]
+  return cardIdIndex[id]
 end
 
 -- Returns a list of cards from the bag matching a class and level (0 or upgraded)
--- Params table:
---     class: String class to retrieve ("Guardian", "Seeker", etc)
---     isUpgraded: true for upgraded cards (Level 1-5), false for Level 0
--- Return: If the indexes are still being constructed, returns an empty table.
---     Otherwise, a list of tables, each with the following fields
---       cardData: TTS object data, suitable for spawning the card
---       cardMetadata: Table of parsed metadata
+---@param params table
+--  class: String class to retrieve ("Guardian", "Seeker", etc)
+--  isUpgraded: true for upgraded cards (Level 1-5), false for Level 0
+---@return table: If the indexes are still being constructed, returns an empty table.
+--  Otherwise, a list of tables, each with the following fields
+--    cardData: TTS object data, suitable for spawning the card
+--    cardMetadata: Table of parsed metadata
 function getCardsByClassAndLevel(params)
   if not isIndexReady() then return {} end
 
@@ -252,6 +253,14 @@ function getCardsByClassAndLevel(params)
   return classAndLevelIndex[params.class..upgradeKey]
 end
 
+-- Returns a list of cards from the bag matching a cycle
+---@param params table
+--  cycle: String cycle to retrieve ("The Scarlet Keys" etc.)
+--  sortByMetadata: true to sort the table by metadata instead of ID
+---@return table: If the indexes are still being constructed, returns an empty table.
+--  Otherwise, a list of tables, each with the following fields
+--    cardData: TTS object data, suitable for spawning the card
+--    cardMetadata: Table of parsed metadata
 function getCardsByCycle(params)
   if not isIndexReady() then return {} end
 

src/playercards/AllCardsBagApi.ttslua

@@ -6,6 +6,7 @@ do
     return guidReferenceApi.getObjectByOwnerAndType("Mythos", "AllCardsBag")
   end
 
+  -- internal function to create a copy of the table to avoid operating on variables owned by different objects
   local function returnCopyOfList(data)
     local copiedList = {}
     for _, id in ipairs(data) do
@@ -15,17 +16,16 @@ do
   end
 
   -- Returns a specific card from the bag, based on ArkhamDB ID
-  ---@param id table String ID of the card to retrieve
-  ---@return table table
-  --  If the indexes are still being constructed, an empty table is
-  --  returned.  Otherwise, a single table with the following fields
+  ---@param id string ID of the card to retrieve
+  ---@return table: If the indexes are still being constructed, returns an empty table.
+  --  Otherwise, a single table with the following fields
   --    cardData: TTS object data, suitable for spawning the card
   --    cardMetadata: Table of parsed metadata
   AllCardsBagApi.getCardById = function(id)
-    return getAllCardsBag().call("getCardById", { id = id })
+    return getAllCardsBag().call("getCardById", id)
   end
 
-  -- Gets a random basic weakness from the bag.  Once a given ID has been returned
+  -- Gets a random basic weakness from the bag. Once a given ID has been returned
   -- it will be removed from the list and cannot be selected again until a reload
   -- occurs or the indexes are rebuilt, which will refresh the list to include all
   -- weaknesses.
@@ -38,17 +38,17 @@ do
     return getAllCardsBag().call("isIndexReady")
   end
 
-  -- Called by Hotfix bags when they load.  If we are still loading indexes, then
+  -- Called by Hotfix bags when they load. If we are still loading indexes, then
   -- the all cards and hotfix bags are being loaded together, and we can ignore
-  -- this call as the hotfix will be included in the initial indexing.  If it is
+  -- this call as the hotfix will be included in the initial indexing. If it is
   -- called once indexing is complete it means the hotfix bag has been added
   -- later, and we should rebuild the index to integrate the hotfix bag.
   AllCardsBagApi.rebuildIndexForHotfix = function()
     getAllCardsBag().call("rebuildIndexForHotfix")
   end
 
-  -- Searches the bag for cards which match the given name and returns a list.  Note that this is
-  -- an O(n) search without index support.  It may be slow.
+  -- Searches the bag for cards which match the given name and returns a list. Note that this is
+  -- an O(n) search without index support. It may be slow.
   ---@param name string or string fragment to search for names
   ---@param exact boolean Whether the name match should be exact
   AllCardsBagApi.getCardsByName = function(name, exact)
@@ -61,15 +61,22 @@ do
 
   -- Returns a list of cards from the bag matching a class and level (0 or upgraded)
   ---@param class string class to retrieve ("Guardian", "Seeker", etc)
-  ---@param upgraded boolean true for upgraded cards (Level 1-5), false for Level 0
+  ---@param upgraded boolean True for upgraded cards (Level 1-5), false for Level 0
   ---@return table: If the indexes are still being constructed, returns an empty table.
-  --     Otherwise, a list of tables, each with the following fields
-  --       cardData: TTS object data, suitable for spawning the card
-  --       cardMetadata: Table of parsed metadata
+  --  Otherwise, a list of tables, each with the following fields
+  --    cardData: TTS object data, suitable for spawning the card
+  --    cardMetadata: Table of parsed metadata
   AllCardsBagApi.getCardsByClassAndLevel = function(class, upgraded)
     return returnCopyOfList(getAllCardsBag().call("getCardsByClassAndLevel", { class = class, upgraded = upgraded }))
   end
 
+  -- Returns a list of cards from the bag matching a cycle
+  ---@param cycle string Cycle to retrieve ("The Scarlet Keys" etc.)
+  ---@param sortByMetadata boolean If true, sorts the table by metadata instead of ID
+  ---@return table: If the indexes are still being constructed, returns an empty table.
+  --  Otherwise, a list of tables, each with the following fields
+  --    cardData: TTS object data, suitable for spawning the card
+  --    cardMetadata: Table of parsed metadata
   AllCardsBagApi.getCardsByCycle = function(cycle, sortByMetadata)
     return returnCopyOfList(getAllCardsBag().call("getCardsByCycle", { cycle = cycle, sortByMetadata = sortByMetadata }))
   end