LoadingScreen: documentation updates

apps/openmw/mwgui/loadingscreen.hpp

@@ -33,11 +33,10 @@ namespace MWGui
         LoadingScreen(const VFS::Manager* vfs, osgViewer::Viewer* viewer);
         virtual ~LoadingScreen();
 
+        /// Overridden from Loading::Listener, see the Loading::Listener documentation for usage details
         virtual void setLabel (const std::string& label);
-
         virtual void loadingOn();
         virtual void loadingOff();
-
         virtual void setProgressRange (size_t range);
         virtual void setProgress (size_t value);
         virtual void increaseProgress (size_t increase=1);

components/loadinglistener/loadinglistener.hpp

@@ -1,23 +1,32 @@
 #ifndef COMPONENTS_LOADINGLISTENER_H
 #define COMPONENTS_LOADINGLISTENER_H
 
+#include <string>
+
 namespace Loading
 {
     class Listener
     {
     public:
+        /// Set a text label to show on the loading screen.
         virtual void setLabel (const std::string& label) {}
 
-        // Use ScopedLoad instead of using these directly
+        /// Start a loading sequence. Must call loadingOff() when done.
+        /// @note To get the loading screen to actually update, you must call setProgress / increaseProgress periodically.
+        /// @note It is best to use the ScopedLoad object instead of using loadingOn()/loadingOff() directly,
+        ///  so that the loading is exception safe.
         virtual void loadingOn() {}
         virtual void loadingOff() {}
 
+        /// Set the total range of progress (e.g. the number of objects to load).
         virtual void setProgressRange (size_t range) {}
+        /// Set current progress. Valid range is [0, progressRange)
         virtual void setProgress (size_t value) {}
+        /// Increase current progress, default by 1.
         virtual void increaseProgress (size_t increase = 1) {}
     };
 
-    // Used for stopping a loading sequence when the object goes out of scope
+    /// @brief Used for stopping a loading sequence when the object goes out of scope
     struct ScopedLoad
     {
         ScopedLoad(Listener* l) : mListener(l) { mListener->loadingOn(); }