Please add caveats to NSDateFormatter documentation about setting a locale for fixed formats

Originator:jalkut
Number:rdar://21115452 Date Originated:26-May-2015 08:41 PM
Status:Open Resolved:
Product:Documentation Product Version:
Classification: Reproducible:
 
Summary:
I spent a long time today convinced that NSDateFormatter was buggy, that its behavior was new, that it didn't perform as advertised, etc. This culminated in a blog post and a bug report (Radar #21105874) which I now realize is not really appropriate. I'm closing that report, because I'm now convinced that I've been using NSDateFormatter wrong.

I take responsibility for my misunderstanding, but it would have been likely avoided if there was a more prominent caveat in the date formatting documentation: 

https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/DataFormatting/Articles/dfDateFormatting10_4.html#

Beginning in the section titled "Use Format Strings to Specify Custom Formats", it outlines precisely the need I wanted to fill: creating strings formatted for use as internet-based date strings. However, I now realize there is a major caveat to this usage that is not covered until farther down in the document, under the "Parsing Date Strings" section. It is here that the strong language is used about specifying the en_US_POSIX encoding to avoid working with a default mix of locale and user preferences.

This caveat shouldn't be confined to the "Parsing" section, as it applies equally to uses of NSDateFormatter that involve generating string representations of dates. It would help a lot of if the caveat were moved from the parsing section up to the area right below "Use Format Strings to Specify Custom Formats." Nearthe general explanation for why format strings are valuable would be a great place to emphasize the caveat about specifying a standard locale to standardize formatter behavior.

Steps to Reproduce:


Expected Results:


Actual Results:


Version:


Notes:


Configuration:


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!