[swift-evolution] [Review] SE-0006 Apply API Guidelines to the Standard Library

[Ben Rimmington]

> On 5 Feb 2016, at 21:35, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Fri Feb 05 2016, Ben Rimmington <swift-evolution at swift.org> wrote:
> 
>> Proposal link:
>> 
>> <https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>
>> 
>>> precondition was renamed to require.
>> 
>> In the Standard Library, "- Requires:" appears in documentation
>> comments more often than "- Precondition:" or "- Postcondition:", so
>> renaming the function makes sense.
>> 
>> However, I think the Xcode Markup Formatting Reference should be
>> updated to reflect this usage. The current description is:
>> 
>>> Use the field to add requirements such as frameworks for using the symbol.
>>> 
>>> /**
>>> An example of using the requires field
>>> 
>>> - requires: Contacts framework
>>> - requires: OS X version 10.11 or better
>>> */
>> 
>> <https://developer.apple.com/library/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/Requires.html>
> 
> And what do you think it *should* say?

You seem to be using the "- Requires:" field as an alternative to the "- Precondition:" field. Here are some examples from the Standard Library (Swift 2.1):

/// - Requires: `start <= end`.
/// - Requires: `count > 0`.
/// - Requires: `i <= count`.
/// - Requires: `s` contains exactly one extended grapheme cluster.
/// - Requires: No preceding call to `self.next()` has returned `nil`.
/// - Requires: The next value is representable.

If this usage is correct, I'm suggesting that the Xcode Markup Formatting Reference pages for "- Requires:" and "- Precondition:" should be basically the same.

To document framework/platform dependencies (that the "- Requires:" field was apparently designed for) you could instead add a new "- Dependency:" field.

-- Ben