Polished docs of ResourceManager API.

src/Magnum/AbstractResourceLoader.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::AbstractResourceLoader
+ * @brief Class @ref Magnum::AbstractResourceLoader
  */
 
 #include <string>
@@ -38,28 +38,30 @@ namespace Magnum {
 /**
 @brief Base for resource loaders
 
-Provides (a)synchronous resource loading for ResourceManager.
+Provides (a)synchronous resource loading for @ref ResourceManager.
 
 @section AbstractResourceLoader-usage Usage and subclassing
 
 Usage is done by subclassing. Subclass instances can be added to
-ResourceManager using ResourceManager::setLoader(). After adding the loader,
-each call to ResourceManager::get() will call load() implementation unless the
-resource is already loaded (or loading is in progress). Note that resources
-requested before the loader was added are not be affected by the loader.
-
-Subclassing is done by implementing at least doLoad() function. The loading can
-be done synchronously or asynchronously (i.e., in another thread). The base
-implementation provides interface to ResourceManager and manages loading
-progress (which is then available through functions requestedCount(),
-loadedCount() and notFoundCount()). You shouldn't access the ResourceManager
-directly when loading the data.
-
-In your doLoad() implementation, after your resources are loaded, call set() to
-pass them to ResourceManager or call setNotFound() to indicate that the
-resource was not found.
-
-You can also implement name() to provide meaningful names for resource keys.
+@ref ResourceManager using @ref ResourceManager::setLoader(). After adding the
+loader, each call to @ref ResourceManager::get() will call @ref load()
+implementation unless the resource is already loaded (or loading is in
+progress). Note that resources requested before the loader was added are not
+affected by the loader.
+
+Subclassing is done by implementing at least @ref doLoad() function. The
+loading can be done synchronously or asynchronously (i.e., in another thread).
+The base implementation provides interface to @ref ResourceManager and manages
+loading progress (which is then available through functions @ref requestedCount(),
+@ref loadedCount() and @ref notFoundCount()). You shouldn't access the
+@ref ResourceManager directly when loading the data.
+
+In your @ref doLoad() implementation, after your resources are loaded, call
+@ref set() to pass them to @ref ResourceManager or call @ref setNotFound() to
+indicate that the resource was not found.
+
+You can also implement @ref name() to provide meaningful names for resource
+keys.
 
 Example implementation for synchronous mesh loader:
 @code
@@ -109,23 +111,23 @@ template<class T> class AbstractResourceLoader {
         /**
          * @brief Count of requested resources
          *
-         * Count of resources requested by calling load().
+         * Count of resources requested by calling @ref load().
          */
         std::size_t requestedCount() const { return _requestedCount; }
 
         /**
          * @brief Count of not found resources
          *
-         * Count of resources requested by calling load(), but not found by
-         * the loader.
+         * Count of resources requested by calling @ref load(), but not found
+         * by the loader.
          */
         std::size_t notFoundCount() const { return _notFoundCount; }
 
         /**
          * @brief Count of loaded resources
          *
-         * Count of resources requested by calling load(), but not found by
-         * the loader.
+         * Count of resources requested by calling @ref load(), but not found
+         * by the loader.
          */
         std::size_t loadedCount() const { return _loadedCount; }
 
@@ -145,8 +147,8 @@ template<class T> class AbstractResourceLoader {
          * features is incremented. Depending on implementation the resource
          * might be loaded synchronously or asynchronously.
          *
-         * @see ResourceManager::state(), requestedCount(), notFoundCount(),
-         *      loadedCount()
+         * @see @ref ResourceManager::state(), @ref requestedCount(),
+         *      @ref notFoundCount(), @ref loadedCount()
          */
         void load(ResourceKey key);
 
@@ -155,9 +157,10 @@ template<class T> class AbstractResourceLoader {
          * @brief Set loaded resource to resource manager
          *
          * Also increments count of loaded resources. Parameter @p state must
-         * be either @ref ResourceDataState::Mutable or @ref ResourceDataState::Final.
-         * See @ref ResourceManager::set() for more information.
-         * @see loadedCount()
+         * be either @ref ResourceDataState::Mutable or
+         * @ref ResourceDataState::Final. See @ref ResourceManager::set() for
+         * more information.
+         * @see @ref loadedCount()
          */
         void set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy);
 
@@ -184,9 +187,9 @@ template<class T> class AbstractResourceLoader {
         /**
          * @brief Mark resource as not found
          *
-         * Also increments count of not found resources. See
-         * ResourceManager::setNotFound() for more information.
-         * @see notFountCount()
+         * Also increments count of not found resources. See also
+         * @ref ResourceManager::set() for more information.
+         * @see @ref notFoundCount()
          */
         void setNotFound(ResourceKey key);
 
@@ -196,14 +199,14 @@ template<class T> class AbstractResourceLoader {
     protected:
     #endif
         /**
-         * @brief Implementation for name()
+         * @brief Implementation for @ref name()
          *
          * Default implementation returns empty string.
          */
         virtual std::string doName(ResourceKey key) const;
 
         /**
-         * @brief Implementation for load()
+         * @brief Implementation for @ref load()
          *
          * See class documentation for reimplementation guide.
          */

src/Magnum/Resource.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::ResourceKey, Magnum::Resource, enum Magnum::ResourceState
+ * @brief Class @ref Magnum::ResourceKey, @ref Magnum::Resource, enum @ref Magnum::ResourceState
  */
 
 #include <Corrade/Utility/Assert.h>
@@ -37,11 +37,11 @@
 
 namespace Magnum {
 
-/** @relates Resource
- * @brief %Resource state
- *
- * @see Resource::state(), ResourceManager::state()
- */
+/**
+@brief %Resource state
+
+@see @ref Resource::state(), @ref ResourceManager::state()
+*/
 enum class ResourceState: UnsignedByte {
     /** The resource is not yet loaded (and no fallback is available). */
     NotLoaded,
@@ -74,9 +74,7 @@ Debug MAGNUM_EXPORT operator<<(Debug debug, ResourceState value);
 /**
 @brief Key for accessing resource
 
-See ResourceManager for more information.
-@see ResourceManager::referenceCount(), ResourceManager::state(),
-    ResourceManager::get(), ResourceManager::set(), Resource::key()
+See @ref ResourceManager for more information.
 */
 class ResourceKey: public Utility::MurmurHash2::Digest {
     public:
@@ -110,7 +108,7 @@ namespace Implementation {
 /**
 @brief %Resource reference
 
-See ResourceManager for more information.
+See @ref ResourceManager for more information.
 */
 #ifdef DOXYGEN_GENERATING_OUTPUT
 template<class T, class U = T>
@@ -125,7 +123,7 @@ class Resource {
          * @brief Default constructor
          *
          * Creates empty resource. Resources are acquired from the manager by
-         * calling ResourceManager::get().
+         * calling @ref ResourceManager::get().
          */
         explicit Resource(): manager(nullptr), lastCheck(0), _state(ResourceState::Final), data(nullptr) {}
 
@@ -157,7 +155,7 @@ class Resource {
         /**
          * @brief %Resource state
          *
-         * @see operator bool(), ResourceManager::state()
+         * @see @ref operator bool(), @ref ResourceManager::state()
          */
         ResourceState state() {
             acquire();

src/Magnum/ResourceManager.h

@@ -26,7 +26,7 @@
 */
 
 /** @file
- * @brief Class Magnum::ResourceManager, enum Magnum::ResourceDataState, Magnum::ResourcePolicy
+ * @brief Class @ref Magnum::ResourceManager, @ref Magnum::ResourceDataState, @ref Magnum::ResourcePolicy
  */
 
 #include <unordered_map>
@@ -35,44 +35,44 @@
 
 namespace Magnum {
 
-/** @relates ResourceManager
- * @brief %Resource data state
- *
- * @see ResourceManager::set(), ResourceState
- */
+/**
+@brief %Resource data state
+
+@see @ref ResourceManager::set(), @ref ResourceState
+*/
 enum class ResourceDataState: UnsignedByte {
     /**
-     * The resource is currently loading. Parameter @p data in ResourceManager::set()
-     * should be set to `null`.
+     * The resource is currently loading. Parameter @p data in
+     * @ref ResourceManager::set() should be set to `nullptr`.
      */
     Loading = UnsignedByte(ResourceState::Loading),
 
     /**
-     * The resource was not found. Parameter @p data in ResourceManager::set()
-     * should be set to `null`.
+     * The resource was not found. Parameter @p data in
+     * @ref ResourceManager::set() should be set to `nullptr`.
      */
     NotFound = UnsignedByte(ResourceState::NotFound),
 
     /**
      * The resource can be changed by the manager in the future. This is
-     * slower, as Resource needs to ask the manager for new version every time
-     * the data are accessed, but allows changing the data for e.g. debugging
-     * purposes.
+     * slower, as @ref Resource needs to ask the manager for new version every
+     * time the data are accessed, but allows changing the data for e.g.
+     * debugging purposes.
      */
     Mutable = UnsignedByte(ResourceState::Mutable),
 
     /**
      * The resource cannot be changed by the manager in the future. This is
-     * faster, as Resource instances will ask for the data only one time, thus
-     * suitable for production code.
+     * faster, as @ref Resource instances will ask for the data only one time,
+     * thus suitable for production code.
      */
     Final = UnsignedByte(ResourceState::Final)
 };
 
-/** @relates ResourceManager
+/**
 @brief %Resource policy
 
-@see ResourceManager::set(), ResourceManager::free()
+@see @ref ResourceManager::set(), @ref ResourceManager::free()
  */
 enum class ResourcePolicy: UnsignedByte {
     /** The resource will stay resident for whole lifetime of resource manager. */
@@ -80,7 +80,7 @@ enum class ResourcePolicy: UnsignedByte {
 
     /**
      * The resource will be unloaded when manually calling
-     * ResourceManager::free() if nothing references it.
+     * @ref ResourceManager::free() if nothing references it.
      */
     Manual,
 
@@ -160,43 +160,43 @@ template<class T> class ResourceManagerData {
 @brief %Resource manager
 
 Provides storage for arbitrary set of types, accessible globally using
-instance().
+@ref instance().
 
 @section ResourceManager-usage Usage
 
-Each resource is referenced from Resource class. For optimizing performance,
-each resource can be set as mutable or final. Mutable resources can be
-modified by the manager and thus each %Resource instance asks the manager for
-modifications on each access. On the other hand, final resources cannot be
-modified by the manager, so %Resource instances don't have to ask the manager
-every time, which is faster.
+Each resource is referenced from @ref Resource class. For optimizing
+performance, each resource can be set as mutable or final. Mutable resources
+can be modified by the manager and thus each @ref Resource instance asks the
+manager for modifications on each access. On the other hand, final resources
+cannot be modified by the manager, so @ref Resource instances don't have to ask
+the manager every time, which is faster.
 
 It's possible to provide fallback for resources which are not available using
-setFallback(). Accessing data of such resources will access the fallback
+@ref setFallback(). Accessing data of such resources will access the fallback
 instead of failing on null pointer dereference. Availability and state of each
-resource can be queried through function state() on the manager or
-Resource::state() on each resource.
+resource can be queried through function @ref state() on the manager or
+@ref Resource::state() on each resource.
 
 The resources can be managed in three ways - resident resources, which stay in
 memory for whole lifetime of the manager, manually managed resources, which
-can be deleted by calling free() if nothing references them anymore, and
+can be deleted by calling @ref free() if nothing references them anymore, and
 reference counted resources, which are deleted as soon as the last reference
 to them is removed.
 
 %Resource state and policy is configured when setting the resource data in
-set() and can be changed each time the data are updated, although already
+@ref set() and can be changed each time the data are updated, although already
 final resources cannot obviously be set as mutable again.
 
 Basic usage is:
-- Typedef'ing manager of desired types, creating its instance.
+-   Typedef'ing manager of desired types, creating its instance.
 @code
 typedef ResourceManager<Mesh, Texture2D, AbstractShaderProgram> MyResourceManager;
 MyResourceManager manager;
 @endcode
-- Filling the manager with resource data and acquiring the resources. Note
-  that a resource can be acquired with get() even before the manager contains
-  the data for it, as long as the resource data are not accessed (or fallback
-  is provided).
+-   Filling the manager with resource data and acquiring the resources. Note
+    that a resource can be acquired with @ref get() even before the manager
+    contains the data for it, as long as the resource data are not accessed (or
+    fallback is provided).
 @code
 MyResourceManager* manager = MyResourceManager::instance();
 Resource<Texture2D> texture(manager->get<Texture2D>("texture"));
@@ -210,13 +210,13 @@ if(!cube) {
     manager->set(cube.key(), mesh, ResourceDataState::Final, ResourcePolicy::Resident);
 }
 @endcode
-- Using the resource data.
+-   Using the resource data.
 @code
 shader->setTexture(layer);
 cube->draw(*shader);
 @endcode
-- Destroying resource references and deleting manager instance when nothing
-  references the resources anymore.
+-   Destroying resource references and deleting manager instance when nothing
+    references the resources anymore.
 
 @see AbstractResourceLoader
 */
@@ -238,7 +238,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * Sets global instance pointer to itself.
          * @attention Only one instance of given ResourceManager type can be
          *      created.
-         * @see instance()
+         * @see @ref instance()
          */
         explicit ResourceManager();
 
@@ -246,7 +246,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * @brief Destructor
          *
          * Sets global instance pointer to `nullptr`.
-         * @see instance()
+         * @see @ref instance()
          */
         ~ResourceManager();
 
@@ -274,7 +274,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
         /**
          * @brief Reference count of given resource
          *
-         * @see set()
+         * @see @ref set()
          */
         template<class T> std::size_t referenceCount(ResourceKey key) const {
             return this->Implementation::ResourceManagerData<T>::referenceCount(key);
@@ -283,7 +283,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
         /**
          * @brief %Resource state
          *
-         * @see set(), Resource::state()
+         * @see @ref set(), @ref Resource::state()
          */
         template<class T> ResourceState state(ResourceKey key) const {
             return this->Implementation::ResourceManagerData<T>::state(key);
@@ -293,20 +293,20 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * @brief Set resource data
          * @return Reference to self (for method chaining)
          *
-         * If @p policy is set to `ResourcePolicy::ReferenceCounted`, there
+         * If @p policy is set to @ref ResourcePolicy::ReferenceCounted, there
          * must be already at least one reference to given resource, otherwise
-         * the data will be deleted immediately and no resource will be
-         * added. To avoid spending unnecessary loading time, add
-         * reference-counted resources only if they are already referenced:
+         * the data will be deleted immediately and no resource will be added.
+         * To avoid spending unnecessary loading time, add reference-counted
+         * resources only if they are already referenced:
          * @code
          * if(manager.referenceCount<T>("myresource")) {
          *     // load data...
          *     manager.set("myresource", data, state, ResourcePolicy::ReferenceCounted);
          * }
          * @endcode
-         * @attention If resource state is already `ResourceState::Final`,
-         *      subsequent updates are not possible.
-         * @see referenceCount(), state()
+         * @attention Subsequent updates are not possible if resource state is
+         *      already @ref ResourceState::Final.
+         * @see @ref referenceCount(), @ref state()
          */
         template<class T> ResourceManager<Types...>& set(ResourceKey key, T* data, ResourceDataState state, ResourcePolicy policy) {
             this->Implementation::ResourceManagerData<T>::set(key, data, state, policy);
@@ -380,7 +380,8 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * @brief Clear all resources of given type
          * @return Reference to self (for method chaining)
          *
-         * Unlike free() this function assumes that no resource is referenced.
+         * Unlike @ref free() this function assumes that no resource is
+         * referenced.
          */
         template<class T> ResourceManager<Types...>& clear() {
             this->Implementation::ResourceManagerData<T>::clear();
@@ -391,7 +392,8 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * @brief Clear all resources
          * @return Reference to self (for method chaining)
          *
-         * Unlike free() this function assumes that no resource is referenced.
+         * Unlike @ref free() this function assumes that no resource is
+         * referenced.
          */
         ResourceManager<Types...>& clear() {
             clearInternal<Types...>();
@@ -413,7 +415,7 @@ template<class... Types> class ResourceManager: private Implementation::Resource
          * @param loader    Loader or `nullptr` if unsetting previous loader.
          * @return Reference to self (for method chaining)
          *
-         * See AbstractResourceLoader documentation for more information.
+         * See @ref AbstractResourceLoader documentation for more information.
          * @attention The loader is deleted on destruction before unloading
          *      all resources.
          */