Added documentation for AppBase (fixed https://github.com/DiligentGraphics/DiligentTools/issues/12)

7 files changed, 120 insertions, 8 deletions

diff --git a/NativeApp/include/Android/AndroidAppBase.hpp b/NativeApp/include/Android/AndroidAppBase.hpp
index 403c62d..dfad320 100644
--- a/NativeApp/include/Android/AndroidAppBase.hpp
+++ b/NativeApp/include/Android/AndroidAppBase.hpp
@@ -35,6 +35,7 @@ struct android_app;
 namespace Diligent
 {
 
+/// Base class for Android applications.
 class AndroidAppBase : public AppBase
 {
 public:
diff --git a/NativeApp/include/AppBase.hpp b/NativeApp/include/AppBase.hpp
index 4f7414b..891594a 100644
--- a/NativeApp/include/AppBase.hpp
+++ b/NativeApp/include/AppBase.hpp
@@ -30,35 +30,102 @@
 namespace Diligent
 {
 
+/// Base class for native applications. Platform-specific classes
+/// such as Win32AppBase, LinuxAppBase are inherited from AppBase.
 class AppBase
 {
 public:
+    /// Golden image capture mode
     enum class GoldenImageMode
     {
+        /// Gloden image processing is disabled
         None = 0,
+
+        /// Capture the golden image. In this mode, the
+        /// application renders one frame, captures it as
+        /// a golden image and exits.
         Capture,
+
+        /// Compare the golden image. In this mode, the application renders
+        /// one frame, compares it with the golden image and exists.
+        /// Zero exit code indicates that the frame is identical to the golden image.
+        /// The non-zero code indicates the number of pixels that differ.
         Compare
     };
 
     virtual ~AppBase() {}
 
-    virtual void        ProcessCommandLine(const char* CmdLine) = 0;
-    virtual const char* GetAppTitle() const                     = 0;
-    virtual void        Update(double CurrTime, double ElapsedTime){};
-    virtual void        Render()                            = 0;
-    virtual void        Present()                           = 0;
-    virtual void        WindowResize(int width, int height) = 0;
-    virtual void        GetDesiredInitialWindowSize(int& width, int& height)
+
+    /// Processes the command line arguments.
+
+    /// The method is called by the framework to let the application process
+    /// the command line arguments. This method is called before any other method is called.
+    /// \param [in] CmdLine - The command line string.
+    virtual void ProcessCommandLine(const char* CmdLine) = 0;
+
+
+    /// Returns the application tile.
+
+    /// An application must override this method to define the application title.
+    /// \return     The application title
+    virtual const char* GetAppTitle() const = 0;
+
+
+    /// Updates the application state.
+
+    /// This method is called by the framework to let the application perform
+    /// the required update operations.
+    /// \param [in] CurrTime    - Current time, i.e. the time elapsed since the application started.
+    /// \param [in] ElapsedTime - The time elapsed since the previous frame update.
+    virtual void Update(double CurrTime, double ElapsedTime){};
+
+
+    /// Renders the frame.
+
+    /// An application must override this method to perform operations
+    /// required to render the frame.
+    virtual void Render() = 0;
+
+
+    /// Presents the frame.
+
+    /// An application must override this method to perform operations
+    /// required to present the rendered frame on the screen.
+    virtual void Present() = 0;
+
+
+    /// Called when the window resizes.
+
+    /// An application must override this method to perform operations
+    /// required to resize the window.
+    /// \param [in] width  - New window width
+    /// \param [in] height - New window height
+    virtual void WindowResize(int width, int height) = 0;
+
+
+    /// Called by the framework to request the desired initial window size.
+
+    /// This method is called before the platform-specific window is created.
+    /// An application may override this method to speciy required initial
+    /// window width and height.
+    virtual void GetDesiredInitialWindowSize(int& width, int& height)
     {
         width  = 0;
         height = 0;
     }
 
+
+    /// Returns the golden image mode, see Diligent::AppBase::GoldenImageMode.
     virtual GoldenImageMode GetGoldenImageMode() const
     {
         return GoldenImageMode::None;
     }
 
+
+    /// Returns the exit code.
+
+    /// An application may override this method to
+    /// return a specific exit code.
     virtual int GetExitCode() const
     {
         return 0;
diff --git a/NativeApp/include/IOS/IOSAppBase.hpp b/NativeApp/include/IOS/IOSAppBase.hpp
index 61a4f0d..1439a72 100644
--- a/NativeApp/include/IOS/IOSAppBase.hpp
+++ b/NativeApp/include/IOS/IOSAppBase.hpp
@@ -29,6 +29,7 @@
 namespace Diligent
 {
 
+/// Base class for iOS applications.
 class IOSAppBase : public AppBase
 {
 public:
diff --git a/NativeApp/include/Linux/LinuxAppBase.hpp b/NativeApp/include/Linux/LinuxAppBase.hpp
index f982b00..9eb1a3a 100644
--- a/NativeApp/include/Linux/LinuxAppBase.hpp
+++ b/NativeApp/include/Linux/LinuxAppBase.hpp
@@ -50,14 +50,38 @@
 namespace Diligent
 {
 
+/// Base class for iOS applications.
 class LinuxAppBase : public AppBase
 {
 public:
+    /// Called when GL context is initialized
+
+    /// An application must override this method to perform requred
+    /// initialization operations after OpenGL context has been initialized
+    /// by the framework
+    /// \param [in] display - XLib display.
+    /// \param [in] window  - XLib window.
     virtual void OnGLContextCreated(Display* display, Window window) = 0;
-    virtual int  HandleXEvent(XEvent* xev) { return 0; }
+
+    /// Handles an XLib event.
+
+    /// An application may override this method to handle XLib events.
+    /// \param [in] xev - XLib event
+    virtual int HandleXEvent(XEvent* xev) { return 0; }
 
 #if VULKAN_SUPPORTED
+    /// Called by the framework to initialize Vulkan.
+
+    /// An application must override this method to initialize Vulkan.
+    /// \param [in] connection - XCB connection
+    /// \param [in] window     - XCB window
+    /// \return     true if the initialization was successful and false otherwise
     virtual bool InitVulkan(xcb_connection_t* connection, uint32_t window) = 0;
+
+    /// Handles an XCB event.
+
+    /// An application may override this method to handle XCB events.
+    /// \param [in] event - XCB event
     virtual void HandleXCBEvent(xcb_generic_event_t* event) {}
 #endif
 };
diff --git a/NativeApp/include/MacOS/MacOSAppBase.hpp b/NativeApp/include/MacOS/MacOSAppBase.hpp
index 87f7702..32361e8 100644
--- a/NativeApp/include/MacOS/MacOSAppBase.hpp
+++ b/NativeApp/include/MacOS/MacOSAppBase.hpp
@@ -29,6 +29,7 @@
 namespace Diligent
 {
 
+/// Base class for MacOS applications.
 class MacOSAppBase : public AppBase
 {
 public:
diff --git a/NativeApp/include/UWP/UWPAppBase.hpp b/NativeApp/include/UWP/UWPAppBase.hpp
index 4eafb2c..359ce7a 100644
--- a/NativeApp/include/UWP/UWPAppBase.hpp
+++ b/NativeApp/include/UWP/UWPAppBase.hpp
@@ -37,6 +37,7 @@
 namespace Diligent
 {
 
+/// Base class for UWP applications.
 class UWPAppBase : public AppBase
 {
 public:
diff --git a/NativeApp/include/Win32/Win32AppBase.hpp b/NativeApp/include/Win32/Win32AppBase.hpp
index 99f7fea..8e9553c 100644
--- a/NativeApp/include/Win32/Win32AppBase.hpp
+++ b/NativeApp/include/Win32/Win32AppBase.hpp
@@ -37,13 +37,30 @@
 namespace Diligent
 {
 
+/// Base class for Win32 applications.
 class Win32AppBase : public AppBase
 {
 public:
+    /// Called by the framework after the window has been created.
+
+    /// \param [in] hWnd         - Window handle.
+    /// \param [in] WindowWidth  - Window width.
+    /// \param [in] WindowHeight - Window height.
+    ///
+    /// \remarks An application may override AppBase::GetDesiredInitialWindowSize
+    ///          method to specify desired initial window size.
     virtual void OnWindowCreated(HWND hWnd,
                                  LONG WindowWidth,
                                  LONG WindowHeight) = 0;
 
+    /// Handles Win32 message
+
+    /// An application may override this method to implement its
+    /// windows message processing routine.
+    /// \param [in] hWnd     - Window handle.
+    /// \param [in] message  - Window message.
+    /// \param [in] wParam   - Window message wparam.
+    /// \param [in] lParam   - Window message lparam.
     virtual LRESULT HandleWin32Message(HWND   hWnd,
                                        UINT   message,
                                        WPARAM wParam,