Documentation|Fonts|Textures: Minor apidoc cleanup

doomsday/client/include/resource/abstractfont.h

@@ -45,6 +45,7 @@ class FontManifest;
 class AbstractFont
 {
 public:
+    /// Notified when the resource is about to be deleted.
     DENG2_DEFINE_AUDIENCE(Deletion, void fontBeingDeleted(AbstractFont const &font))
 
     enum Flag {

doomsday/client/include/resource/fontmanifest.h

@@ -34,7 +34,13 @@ class Fonts;
 class FontScheme;
 
 /**
- * FontManifest. Stores metadata for would-be Font resource.
+ * Description for a would-be logical Font resource.
+ *
+ * Models a reference to and the associated metadata for a logical font in the
+ * font resource collection.
+ *
+ * @see FontScheme, AbstractFont
+ * @ingroup resource
  */
 class FontManifest : public PathTree::Node,
 DENG2_OBSERVES(AbstractFont, Deletion)
@@ -43,8 +49,11 @@ DENG2_OBSERVES(AbstractFont, Deletion)
     /// Required Font instance is missing. @ingroup errors
     DENG2_ERROR(MissingFontError);
 
+    /// Notified when the manifest is about to be deleted.
     DENG2_DEFINE_AUDIENCE(Deletion, void manifestBeingDeleted(FontManifest const &manifest))
-    DENG2_DEFINE_AUDIENCE(UniqueIdChanged, void manifestUniqueIdChanged(FontManifest &manifest))
+
+    /// Notified whenever the unique identifier changes.
+    DENG2_DEFINE_AUDIENCE(UniqueIdChange, void manifestUniqueIdChanged(FontManifest &manifest))
 
 public:
     FontManifest(PathTree::NodeArgs const &args);

doomsday/client/include/resource/fonts.h

@@ -37,12 +37,12 @@
 namespace de {
 
 /**
- * Font resource collection.
+ * Specialized resource collection for a set of logical fonts.
  *
- * There are two general states for a font:
+ * There are two general states for fonts in the collection:
  *
- *   A) Declared but not defined.
- *   B) Declared and defined.
+ *   A) Declared but not defined (only a manifest is present).
+ *   B) Declared and defined (a manifest is present and a resource is associated).
  *
  * @ingroup resource
  */
@@ -169,10 +169,8 @@ DENG2_OBSERVES(AbstractFont, Deletion)
      *
      * @see allSchemes(), Scheme::clear().
      */
-    inline void clearAllSchemes()
-    {
-        foreach(Scheme *scheme, allSchemes())
-        {
+    inline void clearAllSchemes() {
+        foreach(Scheme *scheme, allSchemes()) {
             scheme->clear();
         }
     }
@@ -186,8 +184,7 @@ DENG2_OBSERVES(AbstractFont, Deletion)
      *
      * @return  The associated manifest for this URI.
      */
-    inline Manifest &declare(Uri const &uri)
-    {
+    inline Manifest &declare(Uri const &uri) {
         return scheme(uri.scheme()).declare(uri.path());
     }
 

doomsday/client/include/resource/fontscheme.h

@@ -30,8 +30,14 @@
 
 namespace de {
 
+/**
+ * Font collection resource subspace.
+ *
+ * @see Fonts
+ * @ingroup resource
+ */
 class FontScheme :
-DENG2_OBSERVES(FontManifest, UniqueIdChanged),
+DENG2_OBSERVES(FontManifest, UniqueIdChange),
 DENG2_OBSERVES(FontManifest, Deletion)
 {
     typedef class FontManifest Manifest;
@@ -43,6 +49,7 @@ DENG2_OBSERVES(FontManifest, Deletion)
     /// The specified path was not valid. @ingroup errors
     DENG2_ERROR(InvalidPathError);
 
+    /// Notified whenever a new manifest is defined in the scheme.
     DENG2_DEFINE_AUDIENCE(ManifestDefined, void schemeManifestDefined(FontScheme &scheme, Manifest &manifest))
 
     /// Minimum length of a symbolic name.
@@ -118,7 +125,7 @@ DENG2_OBSERVES(FontManifest, Deletion)
     Index const &index() const;
 
 protected:
-    // Observes Manifest UniqueIdChanged
+    // Observes Manifest UniqueIdChange
     void manifestUniqueIdChanged(Manifest &manifest);
 
     // Observes Manifest Deletion.

doomsday/client/include/resource/resourcesystem.h

@@ -32,6 +32,18 @@
 /**
  * Logical resources; materials, packages, textures, etc...
  *
+ * @par Textures
+ *
+ * @em Clearing a texture is to 'undefine' it - any names bound to it will be
+ * deleted and any GL textures acquired for it are 'released'. The logical
+ * Texture instance used to represent it is also deleted.
+ *
+ * @em Releasing a texture will leave it defined (any names bound to it will
+ * persist) but any GL textures acquired for it are 'released'. Note that the
+ * logical Texture instance used to represent is NOT be deleted.
+ *
+ * @par Fonts
+ *
  * @em Runtime fonts are not loaded until precached or actually needed. They
  * may be cleared, in which case they will be reloaded when needed.
  *

doomsday/client/include/resource/texturemanifest.h

@@ -52,7 +52,7 @@ class TextureManifest : public PathTree::Node,
     DENG2_ERROR(MissingResourceUriError);
 
     DENG2_DEFINE_AUDIENCE(Deletion,        void manifestBeingDeleted    (TextureManifest const &manifest))
-    DENG2_DEFINE_AUDIENCE(UniqueIdChanged, void manifestUniqueIdChanged (TextureManifest &manifest))
+    DENG2_DEFINE_AUDIENCE(UniqueIdChange, void manifestUniqueIdChanged (TextureManifest &manifest))
     DENG2_DEFINE_AUDIENCE(TextureDerived,  void manifestTextureDerived  (TextureManifest &manifest, Texture &texture))
 
 public:

doomsday/client/include/resource/textures.h

@@ -36,24 +36,17 @@ namespace de {
 /**
  * Specialized resource collection for a set of logical textures.
  *
- * @em Clearing a texture is to 'undefine' it - any names bound to it will be
- * deleted and any GL textures acquired for it are 'released'. The logical
- * Texture instance used to represent it is also deleted.
+ * There are two general states for textures in the collection:
  *
- * @em Releasing a texture will leave it defined (any names bound to it will
- * persist) but any GL textures acquired for it are 'released'. Note that the
- * logical Texture instance used to represent is NOT be deleted.
- *
- * Thus there are two general states for textures in the collection:
- *
- *   A) Declared but not defined.
- *   B) Declared and defined.
+ *   A) Declared but not defined (only a manifest is present).
+ *   B) Declared and defined (a manifest is present and a resource is associated).
  *
  * @ingroup resource
  */
-class Textures : DENG2_OBSERVES(TextureScheme, ManifestDefined),
-                 DENG2_OBSERVES(TextureManifest, TextureDerived),
-                 DENG2_OBSERVES(Texture, Deletion)
+class Textures :
+DENG2_OBSERVES(TextureScheme, ManifestDefined),
+DENG2_OBSERVES(TextureManifest, TextureDerived),
+DENG2_OBSERVES(Texture, Deletion)
 {
     /// Internal typedefs for brevity/cleanliness.
     typedef class TextureManifest Manifest;

doomsday/client/include/resource/texturescheme.h

@@ -34,7 +34,7 @@ namespace de {
  * @see Textures
  * @ingroup resource
  */
-class TextureScheme : DENG2_OBSERVES(TextureManifest, UniqueIdChanged),
+class TextureScheme : DENG2_OBSERVES(TextureManifest, UniqueIdChange),
                       DENG2_OBSERVES(TextureManifest, Deletion)
 {
     typedef class TextureManifest Manifest;
@@ -146,7 +146,7 @@ class TextureScheme : DENG2_OBSERVES(TextureManifest, UniqueIdChanged),
     Index const &index() const;
 
 protected:
-    // Observes Manifest UniqueIdChanged
+    // Observes Manifest UniqueIdChange
     void manifestUniqueIdChanged(Manifest &manifest);
 
     // Observes Manifest Deletion.

doomsday/client/src/resource/fontmanifest.cpp

@@ -80,7 +80,7 @@ bool FontManifest::setUniqueId(int newUniqueId)
     d->uniqueId = newUniqueId;
 
     // Notify interested parties that the uniqueId has changed.
-    DENG2_FOR_AUDIENCE(UniqueIdChanged, i) i->manifestUniqueIdChanged(*this);
+    DENG2_FOR_AUDIENCE(UniqueIdChange, i) i->manifestUniqueIdChanged(*this);
 
     return true;
 }

doomsday/client/src/resource/texturemanifest.cpp

@@ -163,7 +163,7 @@ bool TextureManifest::setUniqueId(int newUniqueId)
     d->uniqueId = newUniqueId;
 
     // Notify interested parties that the uniqueId has changed.
-    DENG2_FOR_AUDIENCE(UniqueIdChanged, i) i->manifestUniqueIdChanged(*this);
+    DENG2_FOR_AUDIENCE(UniqueIdChange, i) i->manifestUniqueIdChanged(*this);
 
     return true;
 }