Update changelog and documentation (#1956)

* Update author to Sparkle Project when generating documentation

* Sync change log from 1.27.0

* Add recommendation to not call checkForUpdatesInBackground directly

* Add testing documentation for latsUpdateCheckDate

* Fix formatting with user driver header documentation

CHANGELOG

@@ -54,6 +54,8 @@ If you are migrating from earlier alpha versions of Sparkle 2, please re-familia
  * Fix appcast pubDate tag generation in different locales from #1898 (Sungbin Jo)
  * Create valid xar archives for generating binary delta files from #1906 (Zorg)
  * Fix a few issues with German localization from #1931 (J-rg)
+ * Fix issues with Russian localizations from #1947 (Konstantin Zamyakin)
+ * Fix issues with Czech localizations from #1943 (Vojtěch Koňařík)
  * Add an automated workflow that builds and publishes official Sparkle releases (Tony Arnold, Zorg)
 
 # 1.26.0

InstallerLauncher/SUInstallerLauncher+Private.h

@@ -22,7 +22,7 @@
  This API is not supported when used directly from a Sandboxed applications and will always return @c YES in that case.
  
  @param bundlePath The bundle path to test if authorization is needed when performing an update that replaces this bundle.
- @return @c YES if Sparkle thinks authorization is needed to update the @p bundlePath, otherwise @c NO.
+ @return @c YES if Sparkle thinks authorization is needed to update the @c bundlePath, otherwise @c NO.
  */
 SU_EXPORT BOOL SPUSystemNeedsAuthorizationAccessForBundlePath(NSString *bundlePath);
 

Makefile

@@ -25,7 +25,7 @@ build:
 
 # Need to first gem install jazzy to run this rule
 docs:
-	jazzy --objc --umbrella-header Sparkle/Sparkle.h --framework-root . --readme Documentation/API_README.markdown --theme jony --output Documentation/html
+	jazzy --author "Sparkle Project" --objc --umbrella-header Sparkle/Sparkle.h --framework-root . --readme Documentation/API_README.markdown --theme jony --output Documentation/html
 
 uitest:
 	xcodebuild -scheme UITests -configuration Debug test

Sparkle/SPUUpdater.h

@@ -104,6 +104,10 @@ SU_EXPORT @interface SPUUpdater : NSObject
 /**
  Checks for updates, but does not display any UI unless an update is found.
  
+ You usually do not need to call this method directly. If `automaticallyChecksForUpdates` is @c YES,
+ Sparkle calls this method automatically according to its update schedule using the `updateCheckInterval`
+ and the `lastUpdateCheckDate`.
+ 
  This is meant for programmatically initating a check for updates.
  That is, it will display no UI unless it finds an update, in which case it proceeds as usual.
  This will not find updates that the user has opted into skipping.
@@ -166,7 +170,7 @@ SU_EXPORT @interface SPUUpdater : NSObject
  A property indicating whether or not to check for updates automatically.
  
  By default, Sparkle asks users on second launch for permission if they want automatic update checks enabled
- and sets this property based on their response. If SUEnableAutomaticChecks is set in the Info.plist,
+ and sets this property based on their response. If `SUEnableAutomaticChecks` is set in the Info.plist,
  this permission request is not performed however.
  
  Setting this property will persist in the host bundle's user defaults.
@@ -263,6 +267,10 @@ SU_EXPORT @interface SPUUpdater : NSObject
 
 /**
  The date of the last update check or nil if no check has been performed yet.
+ 
+ For testing purposes, the last update check is stored in the `SULastCheckTime` key in the host bundle's user defaults.
+ For example, `defaults delete my-bundle-id SULastCheckTime` can be invoked to clear the last update check time and test
+ if update checks are automatically scheduled.
  */
 @property (nonatomic, readonly, copy, nullable) NSDate *lastUpdateCheckDate;
 

Sparkle/SPUUserDriver.h

@@ -58,27 +58,27 @@ SU_EXPORT @protocol SPUUserDriver <NSObject>
  * Let the user know a new update is found and ask them what they want to do.
  * Before this point, `-showUserInitiatedUpdateCheckWithCancellation:` may be called.
  *
- * @param appcastItem The Appcast Item containing information that reflects the new update.
+ *  The potential  `stage`s on the updater @c state are:
  *
- * @param state The current state of the user update.
- *  The state.stage values are:
  *  `SPUUpdateStateNotDownloaded` - Update has not been downloaded yet.
+ *
  *  `SPUUpdateStateDownloaded` - Update has already been downloaded but not started installing yet.
+ *
  *  `SPUUpdateStateInstalling` - Update has been downloaded and already started installing.
  *
- *  state.userInitiated indicates if the update was initiated by the user or if it was automatically scheduled in the background.
+ *  The `userIntiated` property on the @c state indicates if the update was initiated by the user or if it was automatically scheduled in the background.
  *
- *  Additionally, these properties on the appcastItem are of importance:
+ *  Additionally, these properties on the @c appcastItem are of importance:
  *
  *  @c appcastItem.informationOnlyUpdate indicates if the update is only informational and should not be downloaded. You can direct the user to the infoURL property of the appcastItem in their web browser. Sometimes information only updates are used as a fallback in case a bad update is shipped, so you'll want to support this case.
  *
  *  @c appcastItem.majorUpgrade indicates if the update is a major or paid upgrade.
  *
  *  @c appcastItem.criticalUpdate indicates if the update is a critical update.
  *
- * @param reply
  * A reply of `SPUUserUpdateChoiceInstall` begins or resumes downloading or installing the update.
- * If the state.stage is `SPUUserUpdateStateInstalling`, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch"). Do not use this reply if @c appcastItem.informationOnlyUpdate is YES.
+ * If the state.stage is `SPUUserUpdateStateInstalling`, this may send a quit event to the application and relaunch it immediately (in this state, this behaves as a fast "install and Relaunch").
+ * Do not use this reply if @c appcastItem.informationOnlyUpdate is YES.
  *
  * A reply of `SPUUserUpdateChoiceDismiss` dismisses the update for the time being. The user may be reminded of the update at a later point.
  * If the state.stage is `SPUUserUpdateStateDownloaded`, the downloaded update is kept after dismissing until the next time an update is shown to the user.
@@ -87,6 +87,10 @@ SU_EXPORT @protocol SPUUserDriver <NSObject>
  * A reply of `SPUUserUpdateChoiceSkip` skips this particular version and won't notify the user again, unless they initiate an update check themselves.
  * If @c appcastItem.majorUpgrade is YES, the major update and any future minor updates to that major release are skipped.
  * If the state.stage is `SPUUpdateStateInstalling`, the installation is also canceled when the update is skipped.
+ *
+ * @param appcastItem The Appcast Item containing information that reflects the new update.
+ * @param state The current state of the user update. See above discussion for notable properties.
+ * @param reply The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details.
  */
 - (void)showUpdateFoundWithAppcastItem:(SUAppcastItem *)appcastItem state:(SPUUserUpdateState *)state reply:(void (^)(SPUUserUpdateChoice))reply;
 
@@ -118,17 +122,17 @@ SU_EXPORT @protocol SPUUserDriver <NSObject>
  * Let the user know a new update was not found after they tried initiating an update check.
  * Before this point, `-showUserInitiatedUpdateCheckWithCancellation:` may be called.
  *
- * @param error The error associated with why a new update was not found.
- *  There are various reasons a new update is unavailable and can't be installed.
- *  This error object is populated with recovery and suggestion strings suitable to be shown in an alert.
+ * There are various reasons a new update is unavailable and can't be installed.
+ * The @c error object is populated with recovery and suggestion strings suitable to be shown in an alert.
  *
- *  The userInfo dictionary is also populated with two keys:
+ * The @c userInfo dictionary on the @c error is also populated with two keys:
  *
- *  `SPULatestAppcastItemFoundKey`: if available, this may provide the latest SUAppcastItem that was found.
+ * `SPULatestAppcastItemFoundKey`: if available, this may provide the latest SUAppcastItem that was found.
  *
- *  `SPUNoUpdateFoundReasonKey`: if available, this will provide the `SUNoUpdateFoundReason`. For example the reason could be because
- *  the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
+ * `SPUNoUpdateFoundReasonKey`: if available, this will provide the `SUNoUpdateFoundReason`. For example the reason could be because
+ * the latest version in the feed requires a newer OS version or could be because the user is already on the latest version.
  *
+ * @param error The error associated with why a new update was not found. See above discussion for more details.
  * @param acknowledgement Acknowledge to the updater that no update found error was shown.
  */
 - (void)showUpdateNotFoundWithError:(NSError *)error acknowledgement:(void (^)(void))acknowledgement;
@@ -208,14 +212,15 @@ SU_EXPORT @protocol SPUUserDriver <NSObject>
  * Let the user know that the update is ready to install and relaunch, and ask them whether they want to proceed.
  * Note if the target application has already terminated, this method may not be invoked.
  *
- * @param reply
  * A reply of `SPUUserUpdateChoiceInstall` installs the update the new update immediately. The application is relaunched only if it is still running by the time this reply is invoked. If the application terminates on its own, Sparkle will attempt to automatically install the update.
  *
  * A reply of `SPUUserUpdateChoiceDismiss` dismisses the update installation for the time being. Note the update may still be installed automatically after the application terminates.
  *
  * A reply of `SPUUserUpdateChoiceSkip` cancels the current update that has begun installing and dismisses the update. In this circumstance, the update is canceled but this update version is not skipped in the future.
  *
  * Before this point, `-showInstallingUpdate` will be called.
+ *
+ * @param reply The reply which indicates if the update should be installed, dismissed, or skipped. See above discussion for more details.
  */
 - (void)showReadyToInstallAndRelaunch:(void (^)(SPUUserUpdateChoice))reply;