Handling Poorly Annotated Objective-C Methods?

Question

It has been awhile since I've worked with Objective-C (and I'm brand new to Swift), so bear with me. However, I've noticed several "nullability annotations" that either don't make sense at all, or completely contradict Apple's documentation. Take the following NSURL class method for example:

+ (instancetype)URLByResolvingBookmarkData:(NSData *)bookmarkData 
                                   options:(NSURLBookmarkResolutionOptions)options 
                             relativeToURL:(NSURL *)relativeURL 
                       bookmarkDataIsStale:(BOOL *)isStale
                                     error:(NSError * _Nullable *)error;

You'll notice that there has been an annotation added to the error parameter, so one should assume this method has been annotated, right?

If that's the case, one would also assume that since the relativeToURL parameter has no nullability annotation added, it is not nullable.

Am I in fact understanding Objective-C's new nullability annotations?

If so, why does the documentation for relativeURL specifically state (bold formatting is mine):

To resolve an app-scoped bookmark, use a value of nil.

I understand the reasoning behind the new annotations, but they have been so hit or miss with existing classes that I don't quite understand the good of them. Am I missing something?

Answer 1

If it says _Nonnull, it can't be nil. If it says _Nullable, it can. Otherwise, at least by default, you can't make any assumptions either way, IIRC.