Scarfski/entt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: used @copydoc where possible

Browse Source
This commit is contained in:
Michele Caini
2018-12-13 22:50:23 +01:00
parent cb9a147fff
commit 9d32a89491
8 changed files with 32 additions and 305 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
src/entt/core/hashed_string.hpp
View File

@@ -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; }
/**

17
src/entt/entity/actor.hpp
View File

@@ -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());
}

9
src/entt/entity/helper.hpp
View File

@@ -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>;

24
src/entt/entity/prototype.hpp
View File

@@ -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());
}

141
src/entt/entity/registry.hpp
View File

@@ -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>);

95
src/entt/entity/sparse_set.hpp
View File

@@ -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();

40
src/entt/meta/meta.hpp
View File

@@ -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());
}

6
src/entt/resource/loader.hpp
View File

@@ -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)...);