return table details in docs

inc/map/map.manager.lua

@@ -6,7 +6,14 @@ local _maps = {}
 
 --- Gets all registered maps as an array.
 --- @within Map
--- @return table An array of registered map data.
+--- @return result table An array of registered map data.
+--- @return result.id string Unique map identifier.
+--- @return result.from_x number Source tile X coordinate in the map sheet.
+--- @return result.from_y number Source tile Y coordinate in the map sheet.
+--- @return result.width number Width in tiles.
+--- @return result.height number Height in tiles.
+--- @return result.to_x number Destination X coordinate on screen.
+--- @return result.to_y number Destination Y coordinate on screen.
 function Map.get_maps_array()
   local maps_array = {}
   for _, map_data in pairs(_maps) do
@@ -17,14 +24,14 @@ end
 
 --- Registers a map definition.
 --- @within Map
--- @param map_data table The map data table.
--- @param map_data.id string Unique map identifier.
--- @param map_data.from_x number Source tile X coordinate in the map sheet.
--- @param map_data.from_y number Source tile Y coordinate in the map sheet.
--- @param map_data.width number Width in tiles.
--- @param map_data.height number Height in tiles.
--- @param map_data.to_x number Destination X coordinate on screen.
--- @param map_data.to_y number Destination Y coordinate on screen.
+--- @param map_data table The map data table.
+--- @param map_data.id string Unique map identifier.
+--- @param map_data.from_x number Source tile X coordinate in the map sheet.
+--- @param map_data.from_y number Source tile Y coordinate in the map sheet.
+--- @param map_data.width number Width in tiles.
+--- @param map_data.height number Height in tiles.
+--- @param map_data.to_x number Destination X coordinate on screen.
+--- @param map_data.to_y number Destination Y coordinate on screen.
 function Map.register(map_data)
   if _maps[map_data.id] then
     trace("Warning: Overwriting map with id: " .. map_data.id)
@@ -34,15 +41,22 @@ end
 
 --- Gets a map by ID.
 --- @within Map
--- @param map_id string The ID of the map.
--- @return table The map data table or nil.
+--- @param map_id string The ID of the map.
+--- @return result table The map data table or nil.
+--- @return result.id string Unique map identifier.
+--- @return result.from_x number Source tile X coordinate in the map sheet.
+--- @return result.from_y number Source tile Y coordinate in the map sheet.
+--- @return result.width number Width in tiles.
+--- @return result.height number Height in tiles.
+--- @return result.to_x number Destination X coordinate on screen.
+--- @return result.to_y number Destination Y coordinate on screen.
 function Map.get_by_id(map_id)
   return _maps[map_id]
 end
 
 --- Draws a map.
 --- @within Map
--- @param map_id string The ID of the map to draw.
+--- @param map_id string The ID of the map to draw.
 function Map.draw(map_id)
   local map_data = Map.get_by_id(map_id)
   if not map_data then