From 444ae73ffb8629efad54706bb394d42d9c3884d0 Mon Sep 17 00:00:00 2001 From: Michele Caini Date: Mon, 22 Apr 2019 17:59:54 +0200 Subject: [PATCH] updated doc --- src/entt/entity/registry.hpp | 76 +++++++++++------------------------- 1 file changed, 22 insertions(+), 54 deletions(-) diff --git a/src/entt/entity/registry.hpp b/src/entt/entity/registry.hpp index c1801db27..dd50342da 100644 --- a/src/entt/entity/registry.hpp +++ b/src/entt/entity/registry.hpp @@ -51,7 +51,7 @@ constexpr exclude_t exclude{}; * The registry is the core class of the entity-component framework.
* It stores entities and arranges pools of components on a per request basis. * By means of a registry, users can manage entities and components and thus - * create views to iterate them. + * create views or groups to iterate them. * * @tparam Entity A valid entity type (see entt_traits for more details). */ @@ -417,9 +417,8 @@ public: * @brief Returns the numeric identifier of a component. * * The given component doesn't need to be necessarily in use.
- * Do not use this functionality to provide numeric identifiers to types at - * runtime, because they aren't guaranteed to be stable between different - * runs. + * Do not use this functionality to generate numeric identifiers for types + * at runtime. They aren't guaranteed to be stable between different runs. * * @tparam Component Type of component to query. * @return Runtime numeric identifier of the given type of component. @@ -538,7 +537,6 @@ public: * `[raw(), raw() + size()]` is always a * valid range, even if the container is empty. * - * @note * There are no guarantees on the order of the components. Use a view if you * want to iterate entities and components in the expected order. * @@ -569,7 +567,6 @@ public: * `[data(), data() + size()]` is always a * valid range, even if the container is empty. * - * @note * There are no guarantees on the order of the entities. Use a view if you * want to iterate entities and components in the expected order. * @@ -614,7 +611,7 @@ public: * @brief Returns the actual version for an entity identifier. * * In case entity identifers are stored around, this function can be used to - * know if they are still valid or the entity has been destroyed and + * know if they are still valid or if the entity has been destroyed and * potentially recycled. * * @warning @@ -683,19 +680,7 @@ public: /** * @brief Assigns each element in a range an entity. * - * There are two kinds of entity identifiers: - * - * * Newly created ones in case no entities have been previously destroyed. - * * Recycled ones with updated versions. - * - * Users should not care about the type of the returned entity identifier. - * In case entity identifers are stored around, the `valid` member - * function can be used to know if they are still valid or the entity has - * been destroyed and potentially recycled. - * - * The entities so generated have assigned the given components, if any. The - * components must be at least default constructible. A compilation error - * will occur otherwhise. + * @sa create * * @tparam Component Types of components to assign to the entity. * @tparam It Type of forward iterator. @@ -911,7 +896,7 @@ public: * Equivalent to the following snippet (pseudocode): * * @code{.cpp} - * auto &component = registry.has(entity) ? registry.get(entity) : registry.assign(entity, value); + * auto &component = registry.has(entity) ? registry.get(entity) : registry.assign(entity, args...); * @endcode * * Prefer this function anyway because it has slightly better performance. @@ -1002,11 +987,7 @@ public: * Equivalent to the following snippet (pseudocode): * * @code{.cpp} - * if(registry.has(entity)) { - * registry.replace(entity, args...); - * } else { - * registry.assign(entity, args...); - * } + * auto &component = registry.has(entity) ? registry.replace(entity, args...) : registry.assign(entity, args...); * @endcode * * Prefer this function anyway because it has slightly better performance. @@ -1040,14 +1021,13 @@ public: * an entity. * * The function type for a listener is equivalent to: + * * @code{.cpp} * void(registry &, Entity, Component &); * @endcode * * Listeners are invoked **after** the component has been assigned to the - * entity. The order of invocation of the listeners isn't guaranteed.
- * Note also that the greater the number of listeners, the greater the - * performance hit when a new component is created. + * entity. The order of invocation of the listeners isn't guaranteed. * * @sa sink * @@ -1067,14 +1047,13 @@ public: * whenever an instance of the given component is explicitly replaced. * * The function type for a listener is equivalent to: + * * @code{.cpp} * void(registry &, Entity, Component &); * @endcode * * Listeners are invoked **before** the component has been replaced. The - * order of invocation of the listeners isn't guaranteed.
- * Note also that the greater the number of listeners, the greater the - * performance hit when a new component is created. + * order of invocation of the listeners isn't guaranteed. * * @sa sink * @@ -1095,14 +1074,13 @@ public: * thus destroyed. * * The function type for a listener is equivalent to: + * * @code{.cpp} * void(registry &, Entity); * @endcode * * Listeners are invoked **before** the component has been removed from the - * entity. The order of invocation of the listeners isn't guaranteed.
- * Note also that the greater the number of listeners, the greater the - * performance hit when a component is destroyed. + * entity. The order of invocation of the listeners isn't guaranteed. * * @sa sink * @@ -1149,9 +1127,7 @@ public: * this member function. * * @warning - * Pools of components that are owned by a group cannot be sorted anymore. - * The group takes the ownership of the pools and arrange components so as - * to iterate them as fast as possible.
+ * Pools of components that are owned by a group cannot be sorted.
* An assertion will abort the execution at runtime in debug mode in case * the pool is owned by a group. * @@ -1197,9 +1173,7 @@ public: * Any subsequent change to `B` won't affect the order in `A`. * * @warning - * Pools of components that are owned by a group cannot be sorted anymore. - * The group takes the ownership of the pools and arrange components so as - * to iterate them as fast as possible.
+ * Pools of components that are owned by a group cannot be sorted.
* An assertion will abort the execution at runtime in debug mode in case * the pool is owned by a group. * @@ -1279,15 +1253,12 @@ public: * The signature of the function should be equivalent to the following: * * @code{.cpp} - * void(const entity_type); + * void(const Entity); * @endcode * - * This function is fairly slow and should not be used frequently.
- * Consider using a view if the goal is to iterate entities that have a - * determinate set of components. A view is usually faster than combining - * this function with a bunch of custom tests.
- * On the other side, this function can be used to iterate all the entities - * that are in use, regardless of their components. + * This function is fairly slow and should not be used frequently. However, + * it's useful for iterating all the entities still in use, regardless of + * their components. * * @tparam Func Type of the function object to invoke. * @param func A valid function object. @@ -1314,12 +1285,9 @@ public: } /** - * @brief Checks if an entity is an orphan. - * - * An orphan is an entity that has no components assigned. - * + * @brief Checks if an entity has components assigned. * @param entity A valid entity identifier. - * @return True if the entity is an orphan, false otherwise. + * @return True if the entity has no components assigned, false otherwise. */ bool orphan(const entity_type entity) const { ENTT_ASSERT(valid(entity)); @@ -1341,7 +1309,7 @@ public: * The signature of the function should be equivalent to the following: * * @code{.cpp} - * void(const entity_type); + * void(const Entity); * @endcode * * This function can be very slow and should not be used frequently.