comment return values, update roadmap

ROADMAP.md

@@ -10,3 +10,6 @@
 - clear chunk's tables instead reallocating them
 - add REQUIRES fragment trait
 - try to keep entity_chunks/places tables as arrays
+- set/assign/insert/remove/destroy for lists?
+- add checks to internal defer commits
+- add attach/detach functions?

evolved.lua

@@ -1677,7 +1677,7 @@ end
 
 ---@param index integer
 ---@param version integer
----@return evolved.id
+---@return evolved.id id
 ---@nodiscard
 function evolved.pack(index, version)
     if index < 1 or index > 0xFFFFF then
@@ -2578,7 +2578,8 @@ end)
 ---
 
 ---@param ... evolved.fragment fragments
----@return evolved.chunk?, evolved.entity[]?
+---@return evolved.chunk? chunk
+---@return evolved.entity[]? chunk_entities
 function evolved.chunk(...)
     local fragment_count = select('#', ...)
 
@@ -2612,7 +2613,7 @@ end
 
 ---@param chunk evolved.chunk
 ---@param ... evolved.fragment fragments
----@return evolved.component[] ... components
+---@return evolved.component_storage ... component_storages
 ---@nodiscard
 function evolved.select(chunk, ...)
     local fragment_count = select('#', ...)
@@ -2662,8 +2663,8 @@ function evolved.select(chunk, ...)
 end
 
 ---@param entity evolved.entity
----@return evolved.each_iterator
----@return evolved.each_state?
+---@return evolved.each_iterator iterator
+---@return evolved.each_state? iterator_state
 ---@nodiscard
 function evolved.each(entity)
     local entity_index = entity % 0x100000
@@ -2691,8 +2692,8 @@ function evolved.each(entity)
 end
 
 ---@param query evolved.query
----@return evolved.execute_iterator
----@return evolved.execute_state?
+---@return evolved.execute_iterator iterator
+---@return evolved.execute_state? iterator_state
 ---@nodiscard
 function evolved.execute(query)
     local query_index = query % 0x100000
@@ -2755,7 +2756,7 @@ end
 local evolved_entity_builder = {}
 evolved_entity_builder.__index = evolved_entity_builder
 
----@return evolved.entity_builder
+---@return evolved.entity_builder builder
 ---@nodiscard
 function evolved.entity()
     ---@type evolved.__entity_builder
@@ -2769,7 +2770,7 @@ end
 
 ---@param fragment evolved.fragment
 ---@param ... any component arguments
----@return evolved.entity_builder
+---@return evolved.entity_builder builder
 function evolved_entity_builder:set(fragment, ...)
     local component = __component_construct(fragment, ...)
 
@@ -2782,7 +2783,7 @@ function evolved_entity_builder:set(fragment, ...)
     return self
 end
 
----@return evolved.entity
+---@return evolved.entity entity
 function evolved_entity_builder:build()
     local fragment_list = self.__fragment_list
     local component_list = self.__component_list
@@ -2819,7 +2820,7 @@ end
 local evolved_fragment_builder = {}
 evolved_fragment_builder.__index = evolved_fragment_builder
 
----@return evolved.fragment_builder
+---@return evolved.fragment_builder builder
 ---@nodiscard
 function evolved.fragment()
     ---@type evolved.__fragment_builder
@@ -2832,27 +2833,27 @@ function evolved.fragment()
     return setmetatable(builder, evolved_fragment_builder)
 end
 
----@return evolved.fragment_builder
+---@return evolved.fragment_builder builder
 function evolved_fragment_builder:tag()
     self.__tag = true
     return self
 end
 
 ---@param default evolved.component
----@return evolved.fragment_builder
+---@return evolved.fragment_builder builder
 function evolved_fragment_builder:default(default)
     self.__default = default
     return self
 end
 
 ---@param construct fun(...): evolved.component
----@return evolved.fragment_builder
+---@return evolved.fragment_builder builder
 function evolved_fragment_builder:construct(construct)
     self.__construct = construct
     return self
 end
 
----@return evolved.fragment
+---@return evolved.fragment fragment
 function evolved_fragment_builder:build()
     local tag = self.__tag
     local default = self.__default
@@ -2893,7 +2894,7 @@ end
 local evolved_query_builder = {}
 evolved_query_builder.__index = evolved_query_builder
 
----@return evolved.query_builder
+---@return evolved.query_builder builder
 ---@nodiscard
 function evolved.query()
     ---@type evolved.__query_builder
@@ -2906,7 +2907,7 @@ function evolved.query()
 end
 
 ---@param ... evolved.fragment fragments
----@return evolved.query_builder
+---@return evolved.query_builder builder
 function evolved_query_builder:include(...)
     local fragment_count = select('#', ...)
 
@@ -2933,7 +2934,7 @@ function evolved_query_builder:include(...)
 end
 
 ---@param ... evolved.fragment fragments
----@return evolved.query_builder
+---@return evolved.query_builder builder
 function evolved_query_builder:exclude(...)
     local fragment_count = select('#', ...)
 
@@ -2959,7 +2960,7 @@ function evolved_query_builder:exclude(...)
     return self
 end
 
----@return evolved.query
+---@return evolved.query query
 function evolved_query_builder:build()
     local include_list = self.__include_list
     local exclude_list = self.__exclude_list