Open Radar

 
Summary:
The documentation for many framework method parameters does not describe what happens when you pass nil or NULL (hereinafter I will just use “nil” to refer to both) to them. Specifically, about half of all pointer or object parameters to NSString methods do not have documented nil behavior.

Steps to Reproduce:
1. Examine, e.g., -[NSString hasPrefix:]’s documentation.

Expected Results:
The documentation tells me whether nil is a valid value.

Actual Results:
The documentation does not.

Notes:
I performed a manual count of parameters to methods mentioned in NSString’s documentation. Excluding deprecated methods and NSError ** parameters, I counted 48 parameters with some sort of description of their behavior when nil (even if it was only “nil is invalid”), and 51 with no such description. Those numbers may be a few off, but they should be close to correct.

The frameworks have a toxic combination of factors with nils:

* nils may be treated as empty content, may trigger special behavior, may do something unexpected but harmless, may be forbidden by assertions, or may cause other kinds of crashes or misbehavior.
* nils often occur in rare error cases that can be difficult to reproduce.
* nils are allowed in any reference type in Objective-C.

The combination of these traits make nils a common source of bugs. Complete documentation of nil behavior can make diagnosing such bugs much easier.

It would also be helpful for methods to indicate if they can return nil. I did not do a similar count for return values, but I would guess that even fewer methods document whether or not they can return nil.