Improve API header docs (sparkle-project#1918)

* Don't expose SPUDownloadData initializer publicly * Make SUAppcast -init unavailable * Fix documented default user agent string * Improve header documentation for SUAppcast(Item) and comparators * Update more API documentation headers Also allow returning nil in -allowedSystemProfileKeysForUpdater: * Clarify documentation on -allowedSystemProfileKeysForUpdater: * Rename willIdleScheduling -> notSchedule for delegate method * Make minor correctness fix for reading info URL
jvimal-eg · Aug 21, 2021 · c6f1cd4 · c6f1cd4
1 parent 306ea26
commit c6f1cd4
Show file tree

Hide file tree

Showing 18 changed files with 528 additions and 148 deletions.
diff --git a/Downloader/SPUDownloader.m b/Downloader/SPUDownloader.m
@@ -11,6 +11,7 @@
 #import "SPULocalCacheDirectory.h"
 #import "SPUURLRequest.h"
 #import "SPUDownloadData.h"
+#import "SPUDownloadDataPrivate.h"
 #import "SUErrors.h"
 
 

diff --git a/Sparkle.xcodeproj/project.pbxproj b/Sparkle.xcodeproj/project.pbxproj
@@ -939,6 +939,7 @@
 		7218EC362623F31C008FECF3 /* org.sparkle-project.InstallerConnection.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = "org.sparkle-project.InstallerConnection.entitlements"; sourceTree = "<group>"; };
 		7218EC372623F32E008FECF3 /* org.sparkle-project.InstallerStatus.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = "org.sparkle-project.InstallerStatus.entitlements"; sourceTree = "<group>"; };
 		7218EC4B2623F51C008FECF3 /* codesign_xpc_service.py */ = {isa = PBXFileReference; lastKnownFileType = text.script.python; path = codesign_xpc_service.py; sourceTree = "<group>"; };
+		721AB11626C777D900D34A86 /* SPUDownloadDataPrivate.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = SPUDownloadDataPrivate.h; sourceTree = "<group>"; };
 		721BC2061D17A532002BC71E /* CoreFoundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreFoundation.framework; path = System/Library/Frameworks/CoreFoundation.framework; sourceTree = SDKROOT; };
 		721BC2081D17A553002BC71E /* Carbon.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Carbon.framework; path = System/Library/Frameworks/Carbon.framework; sourceTree = SDKROOT; };
 		721BC20A1D17A5AD002BC71E /* CoreServices.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreServices.framework; path = System/Library/Frameworks/CoreServices.framework; sourceTree = SDKROOT; };
@@ -1780,6 +1781,7 @@
 			isa = PBXGroup;
 			children = (
 				72F9EC421D5E9ED8004AC8B6 /* SPUDownloadData.h */,
+				721AB11626C777D900D34A86 /* SPUDownloadDataPrivate.h */,
 				72F9EC431D5E9ED8004AC8B6 /* SPUDownloadData.m */,
 				7214B8851D45AD9A00CB5CED /* SPUInstallationType.h */,
 				7293A1AC1CEE933800B957A7 /* SPUURLRequest.h */,

diff --git a/Sparkle/SPUDownloadData.h b/Sparkle/SPUDownloadData.h
@@ -32,8 +32,6 @@ NS_ASSUME_NONNULL_BEGIN
  */
 SU_EXPORT @interface SPUDownloadData : NSObject <NSSecureCoding>
 
-- (instancetype)initWithData:(NSData *)data URL:(NSURL *)URL textEncodingName:(NSString * _Nullable)textEncodingName MIMEType:(NSString * _Nullable)MIMEType;
-
 /**
  * The raw data that was downloaded.
  */

diff --git a/Sparkle/SPUDownloadDataPrivate.h b/Sparkle/SPUDownloadDataPrivate.h
@@ -0,0 +1,19 @@
+//
+//  SPUDownloadDataPrivate.h
+//  SPUDownloadDataPrivate
+//
+//  Created by Mayur Pawashe on 8/13/21.
+//  Copyright © 2021 Sparkle Project. All rights reserved.
+//
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface SPUDownloadData (Private)
+
+- (instancetype)initWithData:(NSData *)data URL:(NSURL *)URL textEncodingName:(NSString * _Nullable)textEncodingName MIMEType:(NSString * _Nullable)MIMEType;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/Sparkle/SPUInstallerDriver.m b/Sparkle/SPUInstallerDriver.m
@@ -12,7 +12,7 @@
 #import "SPUXPCServiceInfo.h"
 #import "SPUUpdaterDelegate.h"
 #import "SUAppcastItem.h"
-#import "SULog.h"
+#import "SUAppcastItem+Private.h"
 #import "SULocalizations.h"
 #import "SUErrors.h"
 #import "SUHost.h"

diff --git a/Sparkle/SPUStandardUserDriver.h b/Sparkle/SPUStandardUserDriver.h
@@ -30,7 +30,7 @@ SU_EXPORT @interface SPUStandardUserDriver : NSObject <SPUUserDriver>
  Initializes a Sparkle's standard user driver for user update interactions
  
  @param hostBundle The target bundle of the host that is being updated.
- @param delegate The delegate to this user driver. Pass nil if you don't want to provide one.
+ @param delegate The optional delegate to this user driver.
  */
 - (instancetype)initWithHostBundle:(NSBundle *)hostBundle delegate:(nullable id<SPUStandardUserDriverDelegate>)delegate;
 

diff --git a/Sparkle/SPUUpdater.h b/Sparkle/SPUUpdater.h
@@ -220,7 +220,7 @@ SU_EXPORT @interface SPUUpdater : NSObject
  The user agent used when checking for updates.
  
  By default the user agent string returned is in the format:
- $(BundleDisplayName)/$(BundleDisplayVersion)/$(SparkleDisplayVersion)
+ $(BundleDisplayName)/$(BundleDisplayVersion) Sparkle/$(SparkleDisplayVersion)
  
  BundleDisplayVersion is derived from the application Info.plist's CFBundleShortVersionString.
  

diff --git a/Sparkle/SPUUpdater.m b/Sparkle/SPUUpdater.m
@@ -403,8 +403,8 @@ - (void)scheduleNextUpdateCheckFiringImmediately:(BOOL)firingImmediately
     [self.updaterTimer invalidate];
 
     if (![self automaticallyChecksForUpdates]) {
-        if ([self.delegate respondsToSelector:@selector(updaterWillIdleSchedulingUpdates:)]) {
-            [self.delegate updaterWillIdleSchedulingUpdates:self];
+        if ([self.delegate respondsToSelector:@selector(updaterWillNotScheduleUpdateCheck:)]) {
+            [self.delegate updaterWillNotScheduleUpdateCheck:self];
         }
         return;
     }
@@ -859,14 +859,16 @@ - (NSURL * _Nullable)parameterizedFeedURL
     NSArray *systemProfile = [SUSystemProfiler systemProfileArrayForHost:self.host];
     if ([self.delegate respondsToSelector:@selector(allowedSystemProfileKeysForUpdater:)]) {
         NSArray * allowedKeys = [self.delegate allowedSystemProfileKeysForUpdater:self];
-        NSMutableArray *filteredProfile = [NSMutableArray array];
-        for (NSDictionary *profileElement in systemProfile) {
-            NSString *key = [profileElement objectForKey:@"key"];
-            if (key && [allowedKeys containsObject:key]) {
-                [filteredProfile addObject:profileElement];
+        if (allowedKeys != nil) {
+            NSMutableArray *filteredProfile = [NSMutableArray array];
+            for (NSDictionary *profileElement in systemProfile) {
+                NSString *key = [profileElement objectForKey:@"key"];
+                if (key && [allowedKeys containsObject:key]) {
+                    [filteredProfile addObject:profileElement];
+                }
             }
+            systemProfile = [filteredProfile copy];
         }
-        systemProfile = [filteredProfile copy];
     }
     return systemProfile;
 }
-Original file line number
+Diff line change
@@ Expand Up / @@ -32,8 +32,6 @@ NS_ASSUME_NONNULL_BEGIN @@
      */
     SU_EXPORT @interface SPUDownloadData : NSObject <NSSecureCoding>
-    - (instancetype)initWithData:(NSData *)data URL:(NSURL *)URL textEncodingName:(NSString * _Nullable)textEncodingName MIMEType:(NSString * _Nullable)MIMEType;
     /**
      * The raw data that was downloaded.
      */
@@ Expand Down @@