Documentation: Minor apidoc improvements for Materials

doomsday/client/include/resource/material.h

@@ -512,7 +512,7 @@ class Material : public de::MapElement
          * Reset the staged animation point for the material. The animation
          * states of all layers and decorations will be rewound to the beginning.
          */
-        void resetAnim();
+        void restartAnimation();
 
         /**
          * Returns the current state of the layer animation @a layerNum for

doomsday/client/include/resource/materials.h

@@ -27,13 +27,11 @@
 #ifdef __CLIENT__
 #  include "MaterialVariantSpec"
 #endif
-#include "def_data.h"
 #include "uri.hh"
 #include <de/Error>
-#include <de/Path>
-#include <de/String>
 #include <QList>
 #include <QMap>
+#include <QSet>
 
 namespace de {
 
@@ -118,10 +116,11 @@ class Materials
      * Construct a new material collection.
      */
     Materials();
-
     virtual ~Materials();
 
-    /// Register the console commands, variables, etc..., of this module.
+    /**
+     * Register the console commands, variables, etc..., of this module.
+     */
     static void consoleRegister();
 
     /**
@@ -245,11 +244,16 @@ class Materials
      */
     inline int groupCount() const { return allGroups().count(); }
 
-    ///
-    Manifest &newManifest(Uri const &uri);
-
-    ///
-    void addMaterial(Material &material);
+    /**
+     * Declare a material in the collection, producing a manifest for a logical
+     * Material which will be defined later. If a manifest with the specified
+     * @a uri already exists the existing manifest will be returned.
+     *
+     * @param uri  Uri representing a path to the material in the virtual hierarchy.
+     *
+     * @return  Manifest for this URI.
+     */
+    Manifest &declare(Uri const &uri);
 
     /**
      * Returns a list of all the unique material instances in the collection,
@@ -258,18 +262,17 @@ class Materials
     All const &all() const;
 
 #ifdef __CLIENT__
-
     /**
-     * Reset all material instance animations back to their initial state.
+     * Rewind all material animations back to their initial/starting state.
      *
-     * @see all(), MaterialVariant::resetAnim()
+     * @see all(), MaterialVariant::restartAnimation()
      */
-    inline void resetAllAnims() const
+    inline void restartAllAnimations() const
     {
         foreach(Material *material, all())
         foreach(MaterialVariant *variant, material->variants())
         {
-            variant->resetAnim();
+            variant->restartAnimation();
         }
     }
 
@@ -310,14 +313,21 @@ class Materials
      */
     void cache(Material &material, VariantSpec const &spec, bool cacheGroups = true);
 
-    /// Process all outstanding tasks in the cache queue.
+    /**
+     * Process all queued material cache tasks.
+     */
     void processCacheQueue();
 
-    /// Empty the Material cache queue, cancelling all outstanding tasks.
+    /**
+     * Cancel all queued material cache tasks.
+     */
     void purgeCacheQueue();
 
 #endif // __CLIENT__
 
+    /// @todo Refactor away:
+    void addMaterial(Material &material);
+
 private:
     DENG2_PRIVATE(d)
 };

doomsday/client/src/dd_main.cpp

@@ -2308,8 +2308,7 @@ void DD_UpdateEngineState(void)
         gx.UpdateState(DD_POST);
 
 #ifdef __CLIENT__
-    // Reset material animations.
-    App_Materials().resetAllAnims();
+    App_Materials().restartAllAnimations();
 #endif
 }
 

doomsday/client/src/def_main.cpp

@@ -1150,7 +1150,7 @@ static void interpretMaterialDef(ded_material_t const &def)
     try
     {
         // Create/retrieve a manifest for the would-be material.
-        MaterialManifest *manifest = &App_Materials().newManifest(*reinterpret_cast<de::Uri *>(def.uri));
+        MaterialManifest *manifest = &App_Materials().declare(*reinterpret_cast<de::Uri *>(def.uri));
 
         // Update manifest classification:
         manifest->setFlags(MaterialManifest::AutoGenerated, CPP_BOOL(def.autoGenerated));

doomsday/client/src/map/p_data.cpp

@@ -182,7 +182,7 @@ DENG_EXTERN_C boolean P_LoadMap(char const *uriCString)
 
 #ifdef __CLIENT__
         // Material animations should begin from their first step.
-        App_Materials().resetAllAnims();
+        App_Materials().restartAllAnimations();
 
         R_InitObjlinkBlockmapForMap();
 

doomsday/client/src/resource/materials.cpp

@@ -356,7 +356,7 @@ bool Materials::has(Uri const &path) const
     return false;
 }
 
-MaterialManifest &Materials::newManifest(de::Uri const &uri)
+MaterialManifest &Materials::declare(de::Uri const &uri)
 {
     LOG_AS("Materials::newManifest");
 

doomsday/client/src/resource/materialvariant.cpp

@@ -170,7 +170,7 @@ Material::Variant::Variant(Material &generalCase, Material::VariantSpec const &s
     : d(new Instance(this, generalCase, spec))
 {
     // Initialize animation states.
-    resetAnim();
+    restartAnimation();
 }
 
 Material::Variant::~Variant()
@@ -263,7 +263,7 @@ void Material::Variant::ticker(timespan_t /*ticLength*/)
     }
 }
 
-void Material::Variant::resetAnim()
+void Material::Variant::restartAnimation()
 {
     // Animation ceases once the material is no longer valid.
     if(!d->material->isValid()) return;