doc: used @copydoc where possible

src/entt/core/hashed_string.hpp

@@ -94,10 +94,7 @@ public:
      */
     constexpr operator const char *() const ENTT_NOEXCEPT { return str; }
 
-    /**
-     * @brief Returns the numeric representation of a hashed string.
-     * @return The numeric representation of the instance.
-     */
+    /*! @copydoc value */
     constexpr operator hash_type() const ENTT_NOEXCEPT { return hash; }
 
     /**

src/entt/entity/actor.hpp

@@ -130,11 +130,7 @@ struct actor {
         return std::as_const(*reg).template get<Component...>(entt);
     }
 
-    /**
-     * @brief Returns references to the given components for an actor.
-     * @tparam Component Types of components to get.
-     * @return References to the components owned by the actor.
-     */
+    /*! @copydoc get */
     template<typename... Component>
     decltype(auto) get() ENTT_NOEXCEPT {
         return reg->template get<Component...>(entt);
@@ -150,11 +146,7 @@ struct actor {
         return std::as_const(*reg).template try_get<Component...>(entt);
     }
 
-    /**
-     * @brief Returns pointers to the given components for an actor.
-     * @tparam Component Types of components to get.
-     * @return Pointers to the components owned by the actor.
-     */
+    /*! @copydoc try_get */
     template<typename... Component>
     auto try_get() ENTT_NOEXCEPT {
         return reg->template try_get<Component...>(entt);
@@ -168,10 +160,7 @@ struct actor {
         return *reg;
     }
 
-    /**
-     * @brief Returns a reference to the underlying registry.
-     * @return A reference to the underlying registry.
-     */
+    /*! @copydoc backend */
     inline registry_type & backend() ENTT_NOEXCEPT {
         return const_cast<registry_type &>(std::as_const(*this).backend());
     }

src/entt/entity/helper.hpp

@@ -74,14 +74,7 @@ template<typename Entity>
 as_view(registry<Entity> &) ENTT_NOEXCEPT -> as_view<false, Entity>;
 
 
-/**
- * @brief Deduction guideline.
- *
- * It allows to deduce the constness of a registry directly from the instance
- * provided to the constructor.
- *
- * @tparam Entity A valid entity type (see entt_traits for more details).
- */
+/*! @copydoc as_view */
 template<typename Entity>
 as_view(const registry<Entity> &) ENTT_NOEXCEPT -> as_view<true, Entity>;
 

src/entt/entity/prototype.hpp

@@ -190,18 +190,7 @@ public:
         }
     }
 
-    /**
-     * @brief Returns references to the given components.
-     *
-     * @warning
-     * Attempting to get a component from a prototype that doesn't own it
-     * results in undefined behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode if the
-     * prototype doesn't own an instance of the given component.
-     *
-     * @tparam Component Types of components to get.
-     * @return References to the components owned by the prototype.
-     */
+    /*! @copydoc get */
     template<typename... Component>
     inline decltype(auto) get() ENTT_NOEXCEPT {
         if constexpr(sizeof...(Component) == 1) {
@@ -226,11 +215,7 @@ public:
         }
     }
 
-    /**
-     * @brief Returns pointers to the given components.
-     * @tparam Component Types of components to get.
-     * @return Pointers to the components owned by the prototype.
-     */
+    /*! @copydoc try_get */
     template<typename... Component>
     inline auto try_get() ENTT_NOEXCEPT {
         if constexpr(sizeof...(Component) == 1) {
@@ -483,10 +468,7 @@ public:
         return *reg;
     }
 
-    /**
-     * @brief Returns a reference to the underlying registry.
-     * @return A reference to the underlying registry.
-     */
+    /*! @copydoc backend */
     inline registry_type & backend() ENTT_NOEXCEPT {
         return const_cast<registry_type &>(std::as_const(*this).backend());
     }

src/entt/entity/registry.hpp

@@ -318,20 +318,7 @@ public:
         return managed<Component>() ? pool<Component>().raw() : nullptr;
     }
 
-    /**
-     * @brief Direct access to the list of components of a given pool.
-     *
-     * The returned pointer is such that range
-     * `[raw<Component>(), raw<Component>() + size<Component>()]` 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.
-     *
-     * @tparam Component Type of component in which one is interested.
-     * @return A pointer to the array of components of the given type.
-     */
+    /*! @copydoc raw */
     template<typename Component>
     inline Component * raw() ENTT_NOEXCEPT {
         return const_cast<Component *>(std::as_const(*this).template raw<Component>());
@@ -662,20 +649,7 @@ public:
         }
     }
 
-    /**
-     * @brief Returns references to the given components for an entity.
-     *
-     * @warning
-     * Attempting to use an invalid entity or to get a component from an entity
-     * that doesn't own it results in undefined behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode in case of
-     * invalid entity or if the entity doesn't own an instance of the given
-     * component.
-     *
-     * @tparam Component Types of components to get.
-     * @param entity A valid entity identifier.
-     * @return References to the components owned by the entity.
-     */
+    /*! @copydoc get */
     template<typename... Component>
     inline decltype(auto) get([[maybe_unused]] const entity_type entity) ENTT_NOEXCEPT {
         if constexpr(sizeof...(Component) == 1) {
@@ -740,18 +714,7 @@ public:
         }
     }
 
-    /**
-     * @brief Returns pointers to the given components for an entity.
-     *
-     * @warning
-     * Attempting to use an invalid entity results in undefined behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode in case of
-     * invalid entity.
-     *
-     * @tparam Component Types of components to get.
-     * @param entity A valid entity identifier.
-     * @return Pointers to the components owned by the entity.
-     */
+    /*! @copydoc try_get */
     template<typename... Component>
     inline auto try_get([[maybe_unused]] const entity_type entity) ENTT_NOEXCEPT {
         if constexpr(sizeof...(Component) == 1) {
@@ -1152,40 +1115,7 @@ public:
         return { &pool<Component>()... };
     }
 
-    /**
-     * @brief Returns a standard view for the given components.
-     *
-     * This kind of views are created on the fly and share with the registry its
-     * internal data structures.<br/>
-     * Feel free to discard a view after the use. Creating and destroying a view
-     * is an incredibly cheap operation because they do not require any type of
-     * initialization.<br/>
-     * As a rule of thumb, storing a view should never be an option.
-     *
-     * Standard views do their best to iterate the smallest set of candidate
-     * entities. In particular:
-     *
-     * * Single component views are incredibly fast and iterate a packed array
-     *   of entities, all of which has the given component.
-     * * Multi component views look at the number of entities available for each
-     *   component and pick up a reference to the smallest set of candidates to
-     *   test for the given components.
-     *
-     * @note
-     * Multi component views are pretty fast. However their performance tend to
-     * degenerate when the number of components to iterate grows up and the most
-     * of the entities have all the given components.<br/>
-     * To get a performance boost, consider using a persistent_view instead.
-     *
-     * @sa view
-     * @sa view<Entity, Component>
-     * @sa persistent_view
-     * @sa raw_view
-     * @sa runtime_view
-     *
-     * @tparam Component Type of components used to construct the view.
-     * @return A newly created standard view.
-     */
+    /*! @copydoc view */
     template<typename... Component>
     inline entt::view<Entity, Component...> view() const {
         static_assert(std::conjunction_v<std::is_const<Component>...>);
@@ -1264,44 +1194,7 @@ public:
         };
     }
 
-    /**
-     * @brief Returns a persistent view for the given components.
-     *
-     * This kind of views are created on the fly and share with the registry its
-     * internal data structures.<br/>
-     * Feel free to discard a view after the use. Creating and destroying a view
-     * is an incredibly cheap operation because they do not require any type of
-     * initialization, but for the first time they are used. That's mainly
-     * because of the internal data structures of the registry that are
-     * dedicated to this kind of views and that don't exist yet the very first
-     * time they are requested.<br/>
-     * As a rule of thumb, storing a view should never be an option.
-     *
-     * Persistent views are the right choice to iterate entities when the number
-     * of components grows up and the most of the entities have all the given
-     * components. They are also the only type of views that supports filters
-     * without incurring in a loss of performance during iterations.<br/>
-     * However, persistent views have also drawbacks:
-     *
-     * * Each kind of persistent view requires a dedicated data structure that
-     *   is allocated within the registry and it increases memory pressure.
-     * * Internal data structures used to construct persistent views must be
-     *   kept updated and it affects slightly construction and destruction of
-     *   entities and components, as well as sort functionalities.
-     *
-     * That being said, persistent views are an incredibly powerful tool if used
-     * with care and offer a boost of performance undoubtedly.
-     *
-     * @sa view
-     * @sa view<Entity, Component>
-     * @sa persistent_view
-     * @sa raw_view
-     * @sa runtime_view
-     *
-     * @tparam Component Types of components used to construct the view.
-     * @tparam Exclude Types of components used to filter the view.
-     * @return A newly created persistent view.
-     */
+    /*! @copydoc persistent_view */
     template<typename... Component, typename... Exclude>
     inline entt::persistent_view<Entity, Component...> persistent_view(type_list<Exclude...> = type_list<>{}) const {
         static_assert(std::conjunction_v<std::is_const<Component>...>);
@@ -1337,29 +1230,7 @@ public:
         return { &pool<Component>() };
     }
 
-    /**
-     * @brief Returns a raw view for the given component.
-     *
-     * This kind of views are created on the fly and share with the registry its
-     * internal data structures.<br/>
-     * Feel free to discard a view after the use. Creating and destroying a view
-     * is an incredibly cheap operation because they do not require any type of
-     * initialization.<br/>
-     * As a rule of thumb, storing a view should never be an option.
-     *
-     * Raw views are incredibly fast and must be considered the best tool to
-     * iterate components whenever knowing the entities to which they belong
-     * isn't required.
-     *
-     * @sa view
-     * @sa view<Entity, Component>
-     * @sa persistent_view
-     * @sa raw_view
-     * @sa runtime_view
-     *
-     * @tparam Component Type of component used to construct the view.
-     * @return A newly created raw view.
-     */
+    /*! @copydoc raw_view */
     template<typename Component>
     inline entt::raw_view<Entity, Component> raw_view() const {
         static_assert(std::is_const_v<Component>);

src/entt/entity/sparse_set.hpp

@@ -672,21 +672,7 @@ public:
         return instances.data();
     }
 
-    /**
-     * @brief Direct access to the array of objects.
-     *
-     * The returned pointer is such that range `[raw(), raw() + size()]` is
-     * 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 sparse set in the expected order.
-     *
-     * @return A pointer to the array of objects.
-     */
+    /*! @copydoc raw */
     object_type * raw() ENTT_NOEXCEPT {
         return instances.data();
     }
@@ -708,34 +694,12 @@ public:
         return const_iterator_type{&instances, pos};
     }
 
-    /**
-     * @brief Returns an iterator to the beginning.
-     *
-     * The returned iterator points to the first instance of the given type. If
-     * the sparse set is empty, the returned iterator will be equal to `end()`.
-     *
-     * @note
-     * Input iterators stay true to the order imposed by a call to either `sort`
-     * or `respect`.
-     *
-     * @return An iterator to the first instance of the given type.
-     */
+    /*! @copydoc cbegin */
     inline const_iterator_type begin() const ENTT_NOEXCEPT {
         return cbegin();
     }
 
-    /**
-     * @brief Returns an iterator to the beginning.
-     *
-     * The returned iterator points to the first instance of the given type. If
-     * the sparse set is empty, the returned iterator will be equal to `end()`.
-     *
-     * @note
-     * Input iterators stay true to the order imposed by a call to either `sort`
-     * or `respect`.
-     *
-     * @return An iterator to the first instance of the given type.
-     */
+    /*! @copydoc begin */
     iterator_type begin() ENTT_NOEXCEPT {
         const typename traits_type::difference_type pos = instances.size();
         return iterator_type{&instances, pos};
@@ -759,38 +723,12 @@ public:
         return const_iterator_type{&instances, {}};
     }
 
-    /**
-     * @brief Returns an iterator to the end.
-     *
-     * The returned iterator points to the element following the last instance
-     * of the given type. Attempting to dereference the returned iterator
-     * results in undefined behavior.
-     *
-     * @note
-     * Input iterators stay true to the order imposed by a call to either `sort`
-     * or `respect`.
-     *
-     * @return An iterator to the element following the last instance of the
-     * given type.
-     */
+    /*! @copydoc cend */
     inline const_iterator_type end() const ENTT_NOEXCEPT {
         return cend();
     }
 
-    /**
-     * @brief Returns an iterator to the end.
-     *
-     * The returned iterator points to the element following the last instance
-     * of the given type. Attempting to dereference the returned iterator
-     * results in undefined behavior.
-     *
-     * @note
-     * Input iterators stay true to the order imposed by a call to either `sort`
-     * or `respect`.
-     *
-     * @return An iterator to the element following the last instance of the
-     * given type.
-     */
+    /*! @copydoc end */
     iterator_type end() ENTT_NOEXCEPT {
         return iterator_type{&instances, {}};
     }
@@ -811,18 +749,7 @@ public:
         return instances[underlying_type::get(entity)];
     }
 
-    /**
-     * @brief Returns the object associated with an entity.
-     *
-     * @warning
-     * Attempting to use an entity that doesn't belong to the sparse set results
-     * in undefined behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode if the
-     * sparse set doesn't contain the given entity.
-     *
-     * @param entity A valid entity identifier.
-     * @return The object associated with the entity.
-     */
+    /*! @copydoc get */
     inline object_type & get(const entity_type entity) ENTT_NOEXCEPT {
         return const_cast<object_type &>(std::as_const(*this).get(entity));
     }
@@ -836,11 +763,7 @@ public:
         return underlying_type::has(entity) ? (instances.data() + underlying_type::get(entity)) : nullptr;
     }
 
-    /**
-     * @brief Returns a pointer to the object associated with an entity, if any.
-     * @param entity A valid entity identifier.
-     * @return The object associated with the entity, if any.
-     */
+    /*! @copydoc try_get */
     inline object_type * try_get(const entity_type entity) ENTT_NOEXCEPT {
         return const_cast<object_type *>(std::as_const(*this).try_get(entity));
     }
@@ -1010,9 +933,7 @@ public:
         }
     }
 
-    /**
-     * @brief Resets a sparse set.
-     */
+    /*! @brief Resets a sparse set. */
     void reset() override {
         underlying_type::reset();
         instances.clear();

src/entt/meta/meta.hpp

@@ -440,10 +440,7 @@ public:
         return instance;
     }
 
-    /**
-     * @brief Returns an opaque pointer to the contained instance.
-     * @return An opaque pointer the contained instance, if any.
-     */
+    /*! @copydoc data */
     inline void * data() ENTT_NOEXCEPT {
         return const_cast<void *>(std::as_const(*this).data());
     }
@@ -479,20 +476,7 @@ public:
         return *internal::try_cast<Type>(node, instance);
     }
 
-    /**
-     * @brief Tries to cast an instance to a given type.
-     *
-     * The type of the instance must be such that the cast is possible.
-     *
-     * @warning
-     * Attempting to perform a cast that isn't viable results in undefined
-     * behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode in case
-     * the cast is not feasible.
-     *
-     * @tparam Type Type to which to cast the instance.
-     * @return A reference to the contained instance.
-     */
+    /*! @copydoc cast */
     template<typename Type>
     inline Type & cast() ENTT_NOEXCEPT {
         return const_cast<Type &>(std::as_const(*this).cast<Type>());
@@ -687,20 +671,7 @@ public:
         return internal::try_cast<Type>(node, instance);
     }
 
-    /**
-     * @brief Tries to cast an instance to a given type.
-     *
-     * The type of the instance must be such that the conversion is possible.
-     *
-     * @warning
-     * Attempting to perform a conversion that isn't viable results in undefined
-     * behavior.<br/>
-     * An assertion will abort the execution at runtime in debug mode in case
-     * the conversion is not feasible.
-     *
-     * @tparam Type Type to which to cast the instance.
-     * @return A pointer to the contained instance.
-     */
+    /*! @copydoc try_cast */
     template<typename Type>
     inline Type * try_cast() ENTT_NOEXCEPT {
         return const_cast<Type *>(std::as_const(*this).try_cast<Type>());
@@ -714,10 +685,7 @@ public:
         return instance;
     }
 
-    /**
-     * @brief Returns an opaque pointer to the contained instance.
-     * @return An opaque pointer the contained instance, if any.
-     */
+    /*! @copydoc data */
     inline void * data() ENTT_NOEXCEPT {
         return const_cast<void *>(std::as_const(*this).data());
     }

src/entt/resource/loader.hpp

@@ -49,6 +49,12 @@ class resource_loader {
     /*! @brief Resource loaders are friends of their caches. */
     friend class resource_cache<Resource>;
 
+    /**
+     * @brief Loads the resource and returns it.
+     * @tparam Args Types of arguments for the loader.
+     * @param args Arguments for the loader.
+     * @return The resource just loaded or an empty pointer in case of errors.
+     */
     template<typename... Args>
     std::shared_ptr<Resource> get(Args &&... args) const {
         return static_cast<const Loader *>(this)->load(std::forward<Args>(args)...);