[swift-evolution] [Review] SE-0006 Apply API Guidelines to the Standard Library
me at benrimmington.com
Fri Feb 5 16:29:29 CST 2016
> 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:
>>> 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
> 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.
More information about the swift-evolution