Document more of VCL's Application class

* Documented the Application class's settings functions. When
reading through the code, I have noticed that GetSettings
intializes the application settings (!) and that SetSettings
relies on GetSettings to initialize the settings (!), so I
have listed a todo entry.

Furthermore, I've also noticed that SetSystemSettings and
MergeSystemSettings may be confused with the purpose of
SetSettings so I've added a todo entry that recommends that
we return an AllSettings object and make the parameters const.

* Minor whitespace changes

* Update @see for a number of public functions

* Group functions into Doxygen modules
Change-Id: I48f8d21a5d6436a2ae545e5156b877d57a8bc585

1 files changed, 142 insertions, 21 deletions

diff --git a/include/vcl/svapp.hxx b/include/vcl/svapp.hxx
index f0fe3ca960be..05d982ace48c 100644
--- a/include/vcl/svapp.hxx
+++ b/include/vcl/svapp.hxx
@@ -268,7 +268,10 @@ public:
     */
     virtual void                UserEvent( sal_uLong nEvent, void* pEventData );
 
-    // Functions that notify when changes occur in the application
+    /** @defgroup changes Change notification functions
+        Functions that notify when changes occur in the application
+        @{
+    */
 
     /** Notify that the application is no longer the "focused" (or current)
         application - needed for Windowing systems where an end user can switch
@@ -287,7 +290,12 @@ public:
     */
     virtual void                DataChanged( const DataChangedEvent& rDCEvt );
 
-    // Initialization functions
+    /** @} */ // end of changes
+
+    /** @defgroup Initialization
+        Initialization functions
+        @{
+    */
 
     /** Initialize the application itself.
 
@@ -313,7 +321,12 @@ public:
     */
     virtual void                DeInit();
 
-    // Command line processing:
+    /** @} */ // end of Initialization
+
+
+    /** @defgroup CommandLine Command line processing
+        @{
+    */
 
     /** Gets the number of command line parameters passed to the application
 
@@ -341,7 +354,12 @@ public:
     */
     static OUString             GetAppFileName();
 
-    // Error handling
+    /** @} */ // end of CommandLine
+
+    /** @defgroup ErrorHandling Error handling
+        @{
+    */
+
     /** Handles an error code.
 
      @remark This is not actually an exception. It merely takes an
@@ -369,13 +387,18 @@ public:
     */
     static void                 Abort( const OUString& rErrorText );
 
-    // Event loop functions:
+    /** @} */ // end of CommandLine
+
+    /** @defgroup EventLoop Event loop functions
+        @{
+    */
 
     /** Run the main event processing loop until it is quit by @Quit.
 
      @see Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static void                 Execute();
 
@@ -383,7 +406,8 @@ public:
 
      @see Execute, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static void                 Quit();
 
@@ -395,8 +419,8 @@ public:
 
      @see Execute, Quit, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
-
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
      */
     static void                 Reschedule( bool bAllEvents = false );
 
@@ -404,7 +428,8 @@ public:
 
      @see Execute, Quit, Reschedule, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static void                 Yield();
 
@@ -412,7 +437,8 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static void                 EndYield();
 
@@ -425,7 +451,8 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, EndYield,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static comphelper::SolarMutex& GetSolarMutex();
 
@@ -435,7 +462,8 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           ReleaseSolarMutex, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static oslThreadIdentifier  GetMainThreadIdentifier();
 
@@ -448,9 +476,9 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, AcquireSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
-
     static sal_uLong            ReleaseSolarMutex();
 
     /** @Brief Acquire Solar Mutex(es) for this thread.
@@ -460,7 +488,8 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex,
-          EnableNoYieldMode, AddPostYieldListener, RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, AddPostYieldListener,
+          RemovePostYieldListener
     */
     static void                 AcquireSolarMutex( sal_uLong nCount );
 
@@ -473,7 +502,7 @@ public:
 
      @see DisableNoYieldMode, Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          AddPostYieldListener, RemovePostYieldListener
+          DisableNoYield, AddPostYieldListener, RemovePostYieldListener
     */
     static void                 EnableNoYieldMode();
 
@@ -486,8 +515,9 @@ public:
 
      @see EnableNoYieldMode, Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          AddPostYieldListener, RemovePostYieldListener
+          EnableNoYield, AddPostYieldListener, RemovePostYieldListener
     */
+
     static void                 DisableNoYieldMode();
 
     /** Add a listener for yield events
@@ -496,18 +526,17 @@ public:
 
      @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          RemovePostYieldListener
+          EnableNoYieldMode, DisableNoYieldMode, RemovePostYieldListener
     */
     static void                 AddPostYieldListener( const Link& i_rListener );
 
-
     /** Remove listener for yield events
 
      @param  i_rListener     Listener to remove
 
      @see Execute, Quit, Reschedule, Yield, EndYield, GetSolarMutex,
           GetMainThreadIdentifier, ReleaseSolarMutex, AcquireSolarMutex,
-          AddPostYieldListener
+          AddPostYieldListener, EnableNoYieldMode, DisableNoYieldMode
     */
     static void                 RemovePostYieldListener( const Link& i_rListener );
 
@@ -562,6 +591,8 @@ public:
     */
     static sal_uLong            GetLastInputInterval();
 
+    /** @} */ // end of EventLoop
+
     /* Determines if the UI is captured.
 
      The UI is considered captured if a system dialog is open (e.g. printer setup),
@@ -572,11 +603,101 @@ public:
      */
     static sal_Bool             IsUICaptured();
 
+    /** defgroup Settings Application settings
+        @{
+    */
+
+    /** Overrides system settings with user settings.
+
+     The system settings that can be overridden are:
+        - window dragging options (on or off, including live scrolling!)
+        - style settings (e.g. cehckbox color, border color, 3D colors,
+          button rollover colors, etc.)
+        - mouse settings
+        - menu options, including the mouse follows the menu and whether menu
+          icons are used
+
+     @remark One wonders why this is a virtual function when all the other
+        settings options are static functions. What is it about overridding
+        an AllSettings object that requires it to have it's own Application
+        instance, when LibreOffice only keeps one Application instance around
+        at any time?
+
+        Another thing about this function is that it is a remarkably awkward
+        name that doesn't \em really describe what it does.
+
+     @todo Recommend that rSettings be made immutable and
+        we return a new AllSettings because as it stands it would be easy to
+        believe that this function changes system settings, which it does not
+        as this is the job of @SetSettings.
+
+     @param      rSettings      Reference to the settings object to change.
+
+     @see MergeSystemSettings, SetSettings, GetSettings
+    */
     virtual void                SystemSettingsChanging( AllSettings& rSettings );
+
+    /** Set the settings object to the platform/desktop environment system
+     settings.
+
+     @todo Incredibly, this gets the default window, then it uses whatever
+        the system settings of this window are. This seems entirely unnecessary.
+        Furthermore, to do this trick it then calls on @ImplUpdateGlobalSettings
+        (a function of the @Window class, which in turn calls on a platform
+        specific SalFrame UpdateSettings to update the settings object to the
+        environment's defaults.
+
+        This would be better refactored to a function that gets the environment's
+        defaults without having to get a Window instance.
+
+     @todo Recommend that rSettings be made immutable and
+        we return a new AllSettings because as it stands it would be easy to
+        believe that this function changes system settings, which it does not
+        as this is the job of @SetSettings.
+
+     @param     rSettings       Reference to the settings object to change.
+
+     @see SystemSettingsChanging, SetSettings, GetSettings
+    */
     static void                 MergeSystemSettings( AllSettings& rSettings );
 
+    /** Sets the application's settings and notifies all windows of the
+     change.
+
+     @todo If the application hasn't initialized its settings yet, then
+        currently it calls on GetSettings to initialize the settings. Recommend
+        moving the initialization to a private function and call on this
+        instead.
+
+     @param     rSettings       const reference to settings object used to
+                                change the application's settings.
+
+     @see SystemSettingsChanging, MergeSystemSettings, GetSettings
+    */
     static void                 SetSettings( const AllSettings& rSettings );
+
+
+    /** Gets the application's settings. If the application hasn't initialized
+     it's settings, then it does so (lazy initialization).
+
+     @remark This is a const function. However, it can update the
+        application's settings object in pSVData. Be warned!
+
+     @todo  We need to call on @GetSettings to initialize the application's
+        settings! This makes absolutely no sense. See @SetSettings, which does
+        exactly this and doesn't care about the return value. Recommend
+        moving this initialization code to a private function and call on
+        this seperately.
+
+     @returns AllSettings instance that contains the current settings of the
+        application.
+
+     @see SystemSettingsChanging, MergeSystemSettings, SetSettings
+    */
     static const AllSettings&   GetSettings();
+
+    /** @} */ // end of Settings
+
     static void                 NotifyAllWindows( DataChangedEvent& rDCEvt );
 
     static void                 AddEventListener( const Link& rEventListener );