Adding some documentation on the setup singleton class

MvvmCross/Core/MvxSetupSingleton.cs

@@ -10,6 +10,29 @@ using MvvmCross.Logging;
 
 namespace MvvmCross.Core
 {
+    /// <summary>
+    /// The setup singleton is designed to ensure only a single instance
+    /// of MvxSetup is created and invoked. There are three important methods
+    /// to the MvxSetupSingleton class:
+    /// EnsureSingletonAvailable - this is a static method that will return 
+    /// the one and only instance of MvxSetupSingleton. This method is protected
+    /// as it's assumed that each platform will provide a platform specific
+    /// public overload for this method which will include any platform parameters
+    /// required
+    /// EnsureInitialized - this is an instance method that should be called 
+    /// to guarrantee that setup has been created and initialized. This method 
+    /// is blocking so make sure it's only called at a point where there
+    /// are no other UI methods are being invoked. This method is typically called
+    /// in applications where there is no splash screen.
+    /// InitializeAndMonitor - this is an instance method that can be called 
+    /// to make sure that the initialization of setup has begun. It registers
+    /// an object to be notified when setup initialization has completed. The callback
+    /// will be raised on the UI thread. This method is not blocking, and doesn't
+    /// guarrantee setup initialize has finished when it returns. This method is 
+    /// typically called by the splash screen view of an application, passing
+    /// itself in as the object to be notified. On notification the splash screen 
+    /// view will trigger navigation to the first view
+    /// </summary>
     public abstract class MvxSetupSingleton
        : MvxSingleton<MvxSetupSingleton>
     {
@@ -20,6 +43,13 @@ namespace MvvmCross.Core
 
         protected virtual IMvxSetup Setup => _setup;
 
+        /// <summary>
+        /// Returns a platform specific instance of Setup
+        /// A useful overload to allow for platform specific
+        /// setup logic to be invoked.
+        /// </summary>
+        /// <typeparam name="TMvxSetup">The platform specific setup type</typeparam>
+        /// <returns>A platform specific instance of Setup</returns>
         public virtual TMvxSetup PlatformSetup<TMvxSetup>()
             where TMvxSetup : IMvxSetup
         {
@@ -34,17 +64,27 @@ namespace MvvmCross.Core
             }
         }
 
+        /// <summary>
+        /// Returns a singleton object that is used to manage the creation and
+        /// execution of setup
+        /// </summary>
+        /// <typeparam name="TMvxSetupSingleton">The platform specific setup singleton type</typeparam>
+        /// <returns>A platform specific setup singleton</returns>
         protected static TMvxSetupSingleton EnsureSingletonAvailable<TMvxSetupSingleton>()
            where TMvxSetupSingleton : MvxSetupSingleton, new()
         {
+            // Double null - check before creating the setup singleton object
             if (Instance != null)
                 return Instance as TMvxSetupSingleton;
-
             lock (LockObject)
             {
                 if (Instance != null)
                     return Instance as TMvxSetupSingleton;
 
+                // Go ahead and create the setup singleton, and then
+                // create the setup instance. 
+                // Note that the Instance property is set within the 
+                // singleton constructor
                 var instance = new TMvxSetupSingleton();
                 instance.CreateSetup();
                 return Instance as TMvxSetupSingleton;