Documentation has incorrect availability

Originator:zach
Number:rdar://29723627 Date Originated:18-Dec-2016 10:45 AM
Status:Closed Resolved:true
Product:Documentation Product Version:N/A
Classification:Other Bug Reproducible:Sometimes
 
Summary:
Correct availability descriptions are important to writing correct and effective Apple software. Many developers use the documentation to find new methods and now if the system provides a given algorithm before writing one themselves. As an iOS instructor, I teach my students to do this as well.

As of the 10.12.2/10.2 releases this week, SDK availability has become much more inaccurate in the unified API Reference.

Steps to Reproduce:
1. Create an empty Swift playground
2. Type "let f: CharacterSet"
3. Cmd-click on "CharacterSet."
4. Locate the type property "CharacterSet.urlQueryAllowed".
5. Open Quickly… > "NSCharacterSet".
6. Likewise, locate the type property "NSCharacterSet.urlQueryAllowed".
7. Find the counterparts in the documentation for 3, 4, 5, and 6.

Expected Results:
In the generated "header", all the above symbols have no availability markers, thus indicating (and is true) that the APIs are available targeting the lowest possible deployment target of Swift. All the above referenced methods should be documented as such.

- CharacterSet should be documented as 8.0/10.10/9.0/2.0.
- CharacterSet.urlQueryAllowed should be documented as 8.0/10.10/9.0/2.0.
- NSCharacterSet should be documented as 2.0/10.0/9.0/2.0.
- NSCharacterSet.urlQueryAllowed should be documented as 7.0/10.9/9.0/2.0.


Actual Results:
The APIs have a mix of incorrectness.

The lowest deployment target for Swift as of Xcode 8/Swift 3 is iOS 8, macOS 10.10, tvOS 9.0 (first public release), and watchOS 2.0 (first public release).

- CharacterSet is documented as 10.0/10.12/10.0/3.0
- CharacterSet.urlQueryAllowed is documented is 10.0/10.12/10.0/3.0.
- NSCharacterSet is documented as 8.0/10.10/9.0/2.0.
- NSCharacterSet.urlQueryAllowed is documented as 7.0/10.9/7.0/2.0.

The above is especially confusing: due to Swift bridging, NSCharacterSet.urlQueryAllowed returns a type that the documentation explicitly says is not available.

Version:
CharacterSet - Foundation
https://developer.apple.com/reference/foundation/characterset

NSCharacterSet - Foundation
https://developer.apple.com/reference/foundation/nscharacterset


Notes:
The problems are not limited to just these locations.

Having historically accurate documentation for APIs is extremely important.

Configuration:
N/A

Attachments:

Comments


Please note: Reports posted here will not necessarily be seen by Apple. All problems should be submitted at bugreport.apple.com before they are posted here. Please only post information for Radars that you have filed yourself, and please do not include Apple confidential information in your posts. Thank you!