GTRepository nullability

Author: Ben Chatelain

ObjectiveGit/GTRepository+Attributes.h

@@ -8,6 +8,8 @@
 
 #import "GTRepository.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (Attributes)
 
 /// Look up the value for the attribute of the given name for the given path.
@@ -16,6 +18,8 @@
 /// path - The path to use for the lookup. Cannot be nil.
 ///
 /// Returns the value of the attribute or nil.
-- (NSString *)attributeWithName:(NSString *)name path:(NSString *)path;
+- (nullable NSString *)attributeWithName:(NSString *)name path:(NSString *)path;
 
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+Committing.h

@@ -8,6 +8,8 @@
 
 #import "GTRepository.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (Committing)
 
 /// Creates a new commit.
@@ -23,10 +25,12 @@
 /// error     - The error if one occurred.
 ///
 /// Returns the newly created commit, or nil if an error occurred.
-- (GTCommit *)createCommitWithTree:(GTTree *)tree message:(NSString *)message author:(GTSignature *)author committer:(GTSignature *)committer parents:(NSArray *)parents updatingReferenceNamed:(NSString *)refName error:(NSError **)error;
+- (nullable GTCommit *)createCommitWithTree:(GTTree *)tree message:(NSString *)message author:(GTSignature *)author committer:(GTSignature *)committer parents:(nullable NSArray *)parents updatingReferenceNamed:(nullable NSString *)refName error:(NSError **)error;
 
 /// Creates a new commit using +createCommitWithTree:message:author:committer:parents:updatingReferenceNamed:error:
 /// with -userSignatureForNow as both the author and committer.
-- (GTCommit *)createCommitWithTree:(GTTree *)tree message:(NSString *)message parents:(NSArray *)parents updatingReferenceNamed:(NSString *)refName error:(NSError **)error;
+- (nullable GTCommit *)createCommitWithTree:(GTTree *)tree message:(NSString *)message parents:(nullable NSArray *)parents updatingReferenceNamed:(nullable NSString *)refName error:(NSError **)error;
 
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+Private.h

@@ -8,7 +8,13 @@
 
 #import "GTRepository.h"
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository ()
-- (id)lookUpObjectByGitOid:(const git_oid *)oid objectType:(GTObjectType)type error:(NSError **)error;
-- (id)lookUpObjectByGitOid:(const git_oid *)oid error:(NSError **)error;
+
+- (nullable id)lookUpObjectByGitOid:(const git_oid *)oid objectType:(GTObjectType)type error:(NSError **)error;
+- (nullable id)lookUpObjectByGitOid:(const git_oid *)oid error:(NSError **)error;
+
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+RemoteOperations.h

@@ -13,27 +13,32 @@
 /// A `GTCredentialProvider`, that will be used to authenticate against the remote.
 extern NSString *const GTRepositoryRemoteOptionsCredentialProvider;
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (RemoteOperations)
 
 #pragma mark - Fetch
 
 /// Fetch a remote.
 ///
-/// remote  - The remote to fetch from.
-/// options - Options applied to the fetch operation.
+/// remote  - The remote to fetch from. Must not be nil.
+/// options - Options applied to the fetch operation. May be nil.
 ///           Recognized options are :
 ///           `GTRepositoryRemoteOptionsCredentialProvider`
 /// error   - The error if one occurred. Can be NULL.
+/// progressBlock - Optional callback to receive fetch progress stats during the
+///                 transfer. May be nil.
 ///
 /// Returns YES if the fetch was successful, NO otherwise (and `error`, if provided,
 /// will point to an error describing what happened).
-- (BOOL)fetchRemote:(GTRemote *)remote withOptions:(NSDictionary *)options error:(NSError **)error progress:(void (^)(const git_transfer_progress *stats, BOOL *stop))progressBlock;
+- (BOOL)fetchRemote:(GTRemote *)remote withOptions:(nullable NSDictionary *)options error:(NSError **)error progress:(nullable void (^)(const git_transfer_progress *stats, BOOL *stop))progressBlock;
 
 /// Enumerate all available fetch head entries.
 ///
 /// error - The error if one ocurred. Can be NULL.
-/// block - A block to execute for each FETCH_HEAD entry. `fetchHeadEntry` will be the current
-///         fetch head entry. Setting `stop` to YES will cause enumeration to stop after the block returns.
+/// block - A block to execute for each FETCH_HEAD entry. `fetchHeadEntry` will
+///         be the current fetch head entry. Setting `stop` to YES will cause
+///         enumeration to stop after the block returns. Must not be nil.
 ///
 /// Returns YES if the operation succedded, NO otherwise.
 - (BOOL)enumerateFetchHeadEntriesWithError:(NSError **)error usingBlock:(void (^)(GTFetchHeadEntry *fetchHeadEntry, BOOL *stop))block;
@@ -42,7 +47,7 @@ extern NSString *const GTRepositoryRemoteOptionsCredentialProvider;
 ///
 /// error - The error if one ocurred. Can be NULL.
 ///
-/// Retruns an array with GTFetchHeadEntry objects
+/// Retruns a (possibly empty) array with GTFetchHeadEntry objects. Will not be nil.
 - (NSArray *)fetchHeadEntriesWithError:(NSError **)error;
 
 #pragma mark - Push
@@ -55,11 +60,11 @@ extern NSString *const GTRepositoryRemoteOptionsCredentialProvider;
 ///                 Recognized options are:
 ///                 `GTRepositoryRemoteOptionsCredentialProvider`
 /// error         - The error if one occurred. Can be NULL.
-/// progressBlock - An optional callback for monitoring progress.
+/// progressBlock - An optional callback for monitoring progress. May be NULL.
 ///
 /// Returns YES if the push was successful, NO otherwise (and `error`, if provided,
 /// will point to an error describing what happened).
-- (BOOL)pushBranch:(GTBranch *)branch toRemote:(GTRemote *)remote withOptions:(NSDictionary *)options error:(NSError **)error progress:(void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
+- (BOOL)pushBranch:(GTBranch *)branch toRemote:(GTRemote *)remote withOptions:(nullable NSDictionary *)options error:(NSError **)error progress:(nullable void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
 
 /// Push an array of branches to a remote.
 ///
@@ -69,10 +74,12 @@ extern NSString *const GTRepositoryRemoteOptionsCredentialProvider;
 ///                 Recognized options are:
 ///                 `GTRepositoryRemoteOptionsCredentialProvider`
 /// error         - The error if one occurred. Can be NULL.
-/// progressBlock - An optional callback for monitoring progress.
+/// progressBlock - An optional callback for monitoring progress. May be NULL.
 ///
 /// Returns YES if the push was successful, NO otherwise (and `error`, if provided,
 /// will point to an error describing what happened).
-- (BOOL)pushBranches:(NSArray *)branches toRemote:(GTRemote *)remote withOptions:(NSDictionary *)options error:(NSError **)error progress:(void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
+- (BOOL)pushBranches:(NSArray *)branches toRemote:(GTRemote *)remote withOptions:(nullable NSDictionary *)options error:(NSError **)error progress:(nullable void (^)(unsigned int current, unsigned int total, size_t bytes, BOOL *stop))progressBlock;
 
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+Reset.h

@@ -17,6 +17,8 @@ typedef NS_ENUM(NSInteger, GTRepositoryResetType) {
 	GTRepositoryResetTypeHard = GIT_RESET_HARD,
 };
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (Reset)
 
 /// Reset the repository's HEAD to the given commit.
@@ -38,3 +40,5 @@ typedef NS_ENUM(NSInteger, GTRepositoryResetType) {
 - (BOOL)resetPathspecs:(NSArray *)pathspecs toCommit:(GTCommit *)commit error:(NSError **)error;
 
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+Stashing.h

@@ -19,6 +19,8 @@ typedef NS_OPTIONS(NSInteger, GTRepositoryStashFlag) {
 	GTRepositoryStashFlagIncludeIgnored = GIT_STASH_INCLUDE_IGNORED
 };
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (Stashing)
 
 /// Stash the repository's changes.
@@ -30,14 +32,14 @@ typedef NS_OPTIONS(NSInteger, GTRepositoryStashFlag) {
 ///
 /// Returns a commit representing the stashed changes if successful, or nil
 /// otherwise.
-- (GTCommit *)stashChangesWithMessage:(NSString *)message flags:(GTRepositoryStashFlag)flags error:(NSError **)error;
+- (nullable GTCommit *)stashChangesWithMessage:(nullable NSString *)message flags:(GTRepositoryStashFlag)flags error:(NSError **)error;
 
 /// Enumerate over all the stashes in the repository, from most recent to oldest.
 ///
 /// block - A block to execute for each stash found. `index` will be the zero-based
 ///         stash index (where 0 is the most recent stash). Setting `stop` to YES
-///         will cause enumeration to stop after the block returns.
-- (void)enumerateStashesUsingBlock:(void (^)(NSUInteger index, NSString *message, GTOID *oid, BOOL *stop))block;
+///         will cause enumeration to stop after the block returns. Must not be nil.
+- (void)enumerateStashesUsingBlock:(void (^)(NSUInteger index, NSString * __nullable message, GTOID * __nullable oid, BOOL *stop))block;
 
 /// Drop a stash from the repository's list of stashes.
 ///
@@ -48,3 +50,5 @@ typedef NS_OPTIONS(NSInteger, GTRepositoryStashFlag) {
 - (BOOL)dropStashAtIndex:(NSUInteger)index error:(NSError **)error;
 
 @end
+
+NS_ASSUME_NONNULL_END

ObjectiveGit/GTRepository+Status.h

@@ -81,6 +81,8 @@ typedef enum {
 /// Defaults to including all files.
 extern NSString *const GTRepositoryStatusOptionsPathSpecArrayKey;
 
+NS_ASSUME_NONNULL_BEGIN
+
 @interface GTRepository (Status)
 
 /// `YES` if the working directory has no modified, new, or deleted files.
@@ -111,12 +113,26 @@ extern NSString *const GTRepositoryStatusOptionsPathSpecArrayKey;
 ///
 /// Returns `NO` in case of a failure or `YES` if the enumeration completed
 /// successfully.
-- (BOOL)enumerateFileStatusWithOptions:(NSDictionary *)options error:(NSError **)error usingBlock:(void (^)(GTStatusDelta *headToIndex, GTStatusDelta *indexToWorkingDirectory, BOOL *stop))block;
+- (BOOL)enumerateFileStatusWithOptions:(nullable NSDictionary *)options error:(NSError **)error usingBlock:(nullable void (^)(GTStatusDelta * __nullable headToIndex, GTStatusDelta * __nullable indexToWorkingDirectory, BOOL *stop))block;
 
 /// Query the status of one file
-- (GTFileStatusFlags)statusForFile:(NSString *)filePath success:(BOOL *)success error:(NSError **)error;
+///
+/// filePath - A string path relative to the working copy. The must not be nil.
+/// success  - If not NULL, will be set to indicate success or fail.
+/// error    - If not nil, set to any error that occurs.
+///
+/// Returns the combined GTFileStatusFlags for the file.
+- (GTFileStatusFlags)statusForFile:(NSString *)filePath success:(nullable BOOL *)success error:(NSError **)error;
 
-/// Should the file be considered as ignored ?
-- (BOOL)shouldFileBeIgnored:(NSURL *)fileURL success:(BOOL *)success error:(NSError **)error;
+/// Tests the ignore rules to see if the file should be considered as ignored.
+///
+/// fileURL  - A string path relative to the working copy. Must not be nil.
+/// success  - If not NULL, will be set to indicate success or fail.
+/// error    - If not nil, set to any error that occurs.
+///
+/// Returns YES if the file should be ignored; NO otherwise.
+- (BOOL)shouldFileBeIgnored:(NSURL *)fileURL success:(nullable BOOL *)success error:(NSError **)error;
 
 @end
+
+NS_ASSUME_NONNULL_END