More ECS API todo's

libs/ecs/include/psemek/ecs/entity_container.hpp

@@ -22,7 +22,8 @@ namespace psemek::ecs
 	using registration_token = std::shared_ptr<void>;
 
 	// TODO:
-	// - Modification callbacks API
+	// - Fully document which functions can be called from which callbacks
+	// - Const-qualified component access
 	// - Modification callbacks implementation
 	// - Index API
 	// - Index implementation
@@ -158,6 +159,11 @@ namespace psemek::ecs
 		 *    the constructor from the entity_container.
 		 *  If any two of the passed component types are equal, the call fails with
 		 *    a compilation error.
+		 *  If the constructor modifies the entity's archetype (i.e. attaches or
+		 *    detaches components), it might be called recursively, leading to
+		 *    infinite recursion. It is best not to change the archetype from the
+		 *    constructor.
+		 *  The constructor can immediately destroy the created entity.
 		 */
 		// TODO: implement
 		template <typename ... Components, typename Function>
@@ -173,11 +179,36 @@ namespace psemek::ecs
 		 *    the destructor from the entity_container.
 		 *  If any two of the passed component types are equal, the call fails with
 		 *    a compilation error.
+		 *  If the destructor modifies the entity's archetype (i.e. attaches or
+		 *    detaches components), the behavior is undefined.
+		 *  Note that there is no way to cancel the entity's destruction.
 		 */
 		// TODO: implement
 		template <typename ... Components, typename Function>
 		registration_token destructor(Function && function);
 
+		/** Register a component modification callback. Each time an entity that has
+		 *    the specified set of components is modified, and the modification only
+		 *    affects this callback's components, the callback is called.
+		 *  If the modification occurred via an entity_accessor, the callback is called
+		 *    when the accessor is destroyed, allowing for transaction-like modification.
+		 *  If the modification occurred via an `apply()` or `batch_apply()` call,
+		 *    the callback is called as if immediately after this call.
+		 *  Note that modifications from within a modification callback are not considered
+		 *    as modifications, i.e. they don't recursively invoke modification callbacks.
+		 *    Therefore, it is best to accept const-qualified components in the callback.
+		 *  The callback must have the same signature as a function
+		 *    passed to the `apply<Components...>()` call.
+		 *  The returned value is an ownerwhip token. Destroying it removes
+		 *    the callback from the entity_container.
+		 *  If any two of the passed component types are equal, the call fails with
+		 *    a compilation error.
+		 *  If the callback modifies the entity's archetype (i.e. attaches or
+		 *    detaches components), or destroys the entity, the behavior is undefined.
+		 */
+		template <typename ... Components, typename Function>
+		registration_token watch(Function && function);
+
 	private:
 		detail::entity_list entity_list_;
 		detail::table_container table_container_;