Add more documentation to SUUpdater.h

flexibits · Sep 5, 2016 · 2268f96 · 2268f96
1 parent c3d8e4b
commit 2268f96
Showing 1 changed file with 127 additions and 38 deletions.
diff --git a/Sparkle/SUUpdater.h b/Sparkle/SUUpdater.h
@@ -32,61 +32,147 @@ SU_EXPORT @interface SUUpdater : NSObject
 
 @property (unsafe_unretained) IBOutlet id<SUUpdaterDelegate> delegate;
 
+/*!
+ The shared updater for the main bundle.
+ 
+ This is equivalent to passing [NSBundle mainBundle] to SUUpdater::updaterForBundle:
+ */
 + (SUUpdater *)sharedUpdater;
+
+/*!
+ The shared updater for a specified bundle.
+
+ If an updater has already been initialized for the provided bundle, that shared instance will be returned.
+ */
 + (SUUpdater *)updaterForBundle:(NSBundle *)bundle;
+
+/*!
+ Designated initializer for SUUpdater.
+ 
+ If an updater has already been initialized for the provided bundle, that shared instance will be returned.
+ */
 - (instancetype)initForBundle:(NSBundle *)bundle;
 
-@property (readonly, strong) NSBundle *hostBundle;
-@property (strong, readonly) NSBundle *sparkleBundle;
+/*!
+ Explicitly checks for updates and displays a progress dialog while doing so.
+
+ This method is meant for a main menu item.
+ Connect any menu item to this action in Interface Builder,
+ and Sparkle will check for updates and report back its findings verbosely
+ when it is invoked.
+
+ This will find updates that the user has opted into skipping.
+ */
+- (IBAction)checkForUpdates:(id)sender;
+
+/*!
+ The menu item validation used for the -checkForUpdates: action
+ */
+- (BOOL)validateMenuItem:(NSMenuItem *)menuItem;
 
+/*!
+ Checks for updates, but does not display any UI unless an update is found.
+
+ This is meant for programmatically initating a check for updates. That is,
+ it will display no UI unless it actually finds an update, in which case it
+ proceeds as usual.
+
+ If automatic downloading of updates it turned on and allowed, however,
+ this will invoke that behavior, and if an update is found, it will be downloaded
+ in the background silently and will be prepped for installation.
+
+ This will not find updates that the user has opted into skipping.
+ */
+- (void)checkForUpdatesInBackground;
+
+/*!
+ A property indicating whether or not to check for updates automatically.
+
+ Setting this property will persist in the host bundle's user defaults.
+ The update schedule cycle will be reset in a short delay after the property's new value is set.
+ This is to allow reverting this property without kicking off a schedule change immediately
+ */
 @property BOOL automaticallyChecksForUpdates;
 
+/*!
+ A property indicating whether or not updates can be automatically downloaded in the background.
+
+ Note that automatic downloading of updates can be disallowed by the developer
+ or by the user's system if silent updates cannot be done (eg: if they require authentication).
+ In this case, -automaticallyDownloadsUpdates will return NO regardless of how this property is set.
+
+ Setting this property will persist in the host bundle's user defaults.
+ */
+@property BOOL automaticallyDownloadsUpdates;
+
+/*!
+ A property indicating the current automatic update check interval.
+
+ Setting this property will persist in the host bundle's user defaults.
+ The update schedule cycle will be reset in a short delay after the property's new value is set.
+ This is to allow reverting this property without kicking off a schedule change immediately
+ */
 @property NSTimeInterval updateCheckInterval;
 
 /*!
- * The URL of the appcast used to download update information.
- *
- * This property must be called on the main thread.
+ Begins a "probing" check for updates which will not actually offer to
+ update to that version.
+
+ However, the delegate methods
+ SUUpdaterDelegate::updater:didFindValidUpdate: and
+ SUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
+ so you can use that information in your UI.
+
+ Updates that have been skipped by the user will not be found.
  */
-@property (copy) NSURL *feedURL;
+- (void)checkForUpdateInformation;
 
-@property (nonatomic, copy) NSString *userAgentString;
+/*!
+ The URL of the appcast used to download update information.
 
-@property (copy) NSDictionary *httpHeaders;
+ Setting this property will persist in the host bundle's user defaults.
+ If you don't want persistence, you may want to consider instead implementing
+ SUUpdaterDelegate::feedURLStringForUpdater: or SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
 
-@property BOOL sendsSystemProfile;
+ This property must be called on the main thread.
+ */
+@property (copy) NSURL *feedURL;
 
-@property BOOL automaticallyDownloadsUpdates;
+/*!
+ The host bundle that is being updated.
+ */
+@property (readonly, strong) NSBundle *hostBundle;
 
-@property (nonatomic, copy) NSString *decryptionPassword;
+/*!
+ The bundle this class (SUUpdater) is loaded into.
+ */
+@property (strong, readonly) NSBundle *sparkleBundle;
 
 /*!
-    Explicitly checks for updates and displays a progress dialog while doing so.
+ The user agent used when checking for updates.
 
-    This method is meant for a main menu item.
-    Connect any menu item to this action in Interface Builder,
-    and Sparkle will check for updates and report back its findings verbosely
-    when it is invoked.
+ The default implementation can be overrided.
  */
-- (IBAction)checkForUpdates:(id)sender;
+@property (nonatomic, copy) NSString *userAgentString;
 
 /*!
-   The menu item validation used for the -checkForUpdates: action
+ The HTTP headers used when checking for updates.
+
+ The keys of this dictionary are HTTP header fields (NSString) and values are corresponding values (NSString)
  */
-- (BOOL)validateMenuItem:(NSMenuItem *)menuItem;
+@property (copy) NSDictionary *httpHeaders;
 
 /*!
-    Checks for updates, but does not display any UI unless an update is found.
+ A property indicating whether or not the user's system profile information is sent when checking for updates.
 
-    This is meant for programmatically initating a check for updates. That is,
-    it will display no UI unless it actually finds an update, in which case it
-    proceeds as usual.
+ Setting this property will persist in the host bundle's user defaults.
+ */
+@property BOOL sendsSystemProfile;
 
-    If the fully automated updating is turned on, however, this will invoke that
-    behavior, and if an update is found, it will be downloaded and prepped for
-    installation.
+/*!
+ A property indicating the decryption password used for extracting updates shipped as Apple Disk Images (dmg)
  */
-- (void)checkForUpdatesInBackground;
+@property (nonatomic, copy) NSString *decryptionPassword;
 
 /*!
     Checks for updates and, if available, immediately downloads and installs them.
@@ -95,6 +181,9 @@ SU_EXPORT @interface SUUpdater : NSObject
 
     You may want to respond to the userDidCancelDownload delegate method in case
     the user clicks the "Cancel" button while the update is downloading.
+
+    If you are writing a UI-less background application, you probably want to instead use
+    SUUpdaterDelegate::updater:willInstallUpdateOnQuit:immediateInstallationInvocation:
  */
 - (void)installUpdatesIfAvailable;
 
@@ -105,17 +194,6 @@ SU_EXPORT @interface SUUpdater : NSObject
  */
 @property (readonly, copy) NSDate *lastUpdateCheckDate;
 
-/*!
-    Begins a "probing" check for updates which will not actually offer to
-    update to that version.
-
-    However, the delegate methods
-    SUUpdaterDelegate::updater:didFindValidUpdate: and
-    SUUpdaterDelegate::updaterDidNotFindUpdate: will be called,
-    so you can use that information in your UI.
- */
-- (void)checkForUpdateInformation;
-
 /*!
     Appropriately schedules or cancels the update checking timer according to
     the preferences for time interval and automatic checks.
@@ -125,6 +203,12 @@ SU_EXPORT @interface SUUpdater : NSObject
  */
 - (void)resetUpdateCycle;
 
+/*!
+   A property indicating whether or not an update is in progress.
+
+   Note this property is not indicative of whether or not user initiated updates can be performed.
+   Use SUUpdater::validateMenuItem: for that instead.
+ */
 @property (readonly) BOOL updateInProgress;
 
 @end
@@ -181,6 +265,9 @@ SU_EXPORT extern NSString *const SUUpdaterAppcastNotificationKey;
 
     Override this to dynamically specify the entire URL.
 
+    An alternative may be to use SUUpdaterDelegate::feedParametersForUpdater:sendingSystemProfile:
+    and let the server handle what kind of feed to provide.
+
     \param updater The SUUpdater instance.
  */
 - (NSString *)feedURLStringForUpdater:(SUUpdater *)updater;
@@ -347,6 +434,8 @@ SU_EXPORT extern NSString *const SUUpdaterAppcastNotificationKey;
 
 /*!
     Called when an update is scheduled to be silently installed on quit.
+    This is after an update has been automatically downloaded in the background.
+    (i.e. SUUpdater::automaticallyDownloadsUpdates is YES)
 
     \param updater The SUUpdater instance.
     \param item The appcast item corresponding to the update that is proposed to be installed.