doc: more details on the order of components and entities when iterating through pointers returned from raw/data (close #489)

src/entt/entity/group.hpp

@@ -158,8 +158,8 @@ public:
      * valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the components. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Components are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Component Type of component in which one is interested.
      * @return A pointer to the array of components.
@@ -177,8 +177,8 @@ public:
      * valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Component Type of component in which one is interested.
      * @return A pointer to the array of entities.
@@ -195,8 +195,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of entities.
      */
@@ -374,11 +374,6 @@ public:
      * * An iterator past the last element of the range to sort.
      * * A comparison function to use to compare the elements.
      *
-     * @note
-     * Attempting to iterate elements using a raw pointer returned by a call to
-     * either `data` or `raw` gives no guarantees on the order, even though
-     * `sort` has been invoked.
-     *
      * @tparam Component Optional types of components to compare.
      * @tparam Compare Type of comparison function object.
      * @tparam Sort Type of sort function object.
@@ -573,8 +568,8 @@ public:
      * the instances that are part of the group itself.
      *
      * @note
-     * There are no guarantees on the order of the components. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Components are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Component Type of component in which one is interested.
      * @return A pointer to the array of components.
@@ -595,8 +590,8 @@ public:
      * contains the entities that are part of the group itself.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Component Type of component in which one is interested.
      * @return A pointer to the array of entities.
@@ -613,8 +608,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the group in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of entities.
      */
@@ -803,11 +798,6 @@ public:
      * * An iterator past the last element of the range to sort.
      * * A comparison function to use to compare the elements.
      *
-     * @note
-     * Attempting to iterate elements using a raw pointer returned by a call to
-     * either `data` or `raw` gives no guarantees on the order, even though
-     * `sort` has been invoked.
-     *
      * @tparam Component Optional types of components to compare.
      * @tparam Compare Type of comparison function object.
      * @tparam Sort Type of sort function object.

src/entt/entity/observer.hpp

@@ -353,8 +353,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the observer in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of entities.
      */

src/entt/entity/registry.hpp

@@ -360,8 +360,8 @@ public:
      * `[raw<Component>(), raw<Component>() + size<Component>()]` is always a
      * valid range, even if the container is empty.
      *
-     * 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.
+     * Components are in the reverse order as imposed by the sorting
+     * functionalities.
      *
      * @note
      * Empty components aren't explicitly instantiated. Therefore, this function
@@ -388,8 +388,8 @@ public:
      * `[data<Component>(), data<Component>() + size<Component>()]` is always a
      * valid range, even if the container is empty.
      *
-     * 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.
+     * Entities are in the reverse order as imposed by the sorting
+     * functionalities.
      *
      * @tparam Component Type of component in which one is interested.
      * @return A pointer to the array of entities.

src/entt/entity/sparse_set.hpp

@@ -33,14 +33,9 @@ namespace entt {
  * purpose of the framework.
  *
  * @note
- * There are no guarantees that entities are returned in the insertion order
- * when iterate a sparse set. Do not make assumption on the order in any case.
- *
- * @note
- * Internal data structures arrange elements to maximize performance. Because of
- * that, there are no guarantees that elements have the expected order when
- * iterate directly the internal packed array (see `data` and `size` member
- * functions for that). Use `begin` and `end` instead.
+ * Internal data structures arrange elements to maximize performance. There are
+ * no guarantees that entities are returned in the insertion order when iterate
+ * a sparse set. Do not make assumption on the order in any case.
  *
  * @tparam Entity A valid entity type (see entt_traits for more details).
  */
@@ -273,11 +268,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order, even though `respect` has been
-     * previously invoked. Internal data structures arrange elements to maximize
-     * performance. Accessing them directly gives a performance boost but less
-     * guarantees. Use `begin` and `end` if you want to iterate the sparse set
-     * in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the internal packed array.
      */
@@ -469,11 +461,6 @@ public:
      * * An iterator past the last element of the range to sort.
      * * A comparison function to use to compare the elements.
      *
-     * @note
-     * Attempting to iterate elements using a raw pointer returned by a call to
-     * `data` gives no guarantees on the order, even though `sort` has been
-     * invoked.
-     *
      * @tparam Compare Type of comparison function object.
      * @tparam Sort Type of sort function object.
      * @tparam Args Types of arguments to forward to the sort function object.
@@ -566,11 +553,6 @@ public:
      * the expected order after a call to `respect`. See `begin` and `end` for
      * more details.
      *
-     * @note
-     * Attempting to iterate elements using a raw pointer returned by a call to
-     * `data` gives no guarantees on the order, even though `respect` has been
-     * invoked.
-     *
      * @param other The sparse sets that imposes the order of the entities.
      */
     void respect(const sparse_set &other) {

src/entt/entity/storage.hpp

@@ -31,10 +31,9 @@ namespace entt {
  * iterators.
  *
  * @note
- * Internal data structures arrange elements to maximize performance. Because of
- * that, there are no guarantees that elements have the expected order when
- * iterate directly the internal packed array (see `raw` and `size` member
- * functions for that). Use `begin` and `end` instead.
+ * Internal data structures arrange elements to maximize performance. There are
+ * no guarantees that objects are returned in the insertion order when iterate
+ * a storage. Do not make assumption on the order in any case.
  *
  * @warning
  * Empty types aren't explicitly instantiated. Therefore, many of the functions
@@ -194,11 +193,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order, even though either `sort` or
-     * `respect` has been previously invoked. Internal data structures arrange
-     * elements to maximize performance. Accessing them directly gives a
-     * performance boost but less guarantees. Use `begin` and `end` if you want
-     * to iterate the storage in the expected order.
+     * Objects are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of objects.
      */
@@ -434,11 +430,6 @@ public:
      * * An iterator past the last element of the range to sort.
      * * A comparison function to use to compare the elements.
      *
-     * @note
-     * Attempting to iterate elements using a raw pointer returned by a call to
-     * either `data` or `raw` gives no guarantees on the order, even though
-     * `sort` has been invoked.
-     *
      * @warning
      * Empty types are never instantiated. Therefore, only comparison function
      * objects that require to return entities rather than components are

src/entt/entity/view.hpp

@@ -269,8 +269,8 @@ public:
      * if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the components. Use `begin` and
-     * `end` if you want to iterate the view in the expected order.
+     * Components are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Comp Type of component in which one is interested.
      * @return A pointer to the array of components.
@@ -288,8 +288,8 @@ public:
      * even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the view in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @tparam Comp Type of component in which one is interested.
      * @return A pointer to the array of entities.
@@ -544,8 +544,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the components. Use `begin` and
-     * `end` if you want to iterate the view in the expected order.
+     * Components are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of components.
      */
@@ -560,8 +560,8 @@ public:
      * always a valid range, even if the container is empty.
      *
      * @note
-     * There are no guarantees on the order of the entities. Use `begin` and
-     * `end` if you want to iterate the view in the expected order.
+     * Entities are in the reverse order as returned by the `begin`/`end`
+     * iterators.
      *
      * @return A pointer to the array of entities.
      */