[XCTAssert] Document file and line params, as well as where assert functions may be used

XCTest/XCTAssert.swift

@@ -10,13 +10,62 @@
 //  XCTAssert.swift
 //
 
-/**
-The primitive assertion function for XCTest. All other XCTAssert* functions are implemented in terms of this. This function emits a test failure if the general Bool expression passed to it evaluates to false.
-- Parameter expression: A boolean test. If it evaluates to false, the assertion fails and emits a test failure.
-- Parameter message: An optional message to use in the failure if the assetion fails. If no message is supplied a default message is used.
-- Parameter file: The file name to use in the error message if the assertion fails. Default is the file containing the call to this function. It is rare to provide this parameter when calling this function.
-- Parameter line: The line number to use in the error message if the assertion fails. Default is the line number of the call to this function in the calling file. It is rare to provide this parameter when calling this function.
-*/
+/// The primitive assertion function for XCTest. All other XCTAssert* functions
+/// are implemented in terms of this. This function emits a test failure if the
+/// general Bool expression passed to it evaluates to false.
+///
+/// - Requires: This and all other XCTAssert* functions must be called from
+///   within a test method, as indicated by `XCTestCaseProvider.allTests`.
+///   Assertion failures that occur outside of a test method will *not* be
+///   reported as failures.
+///
+/// - Parameter expression: A boolean test. If it evaluates to false, the
+///   assertion fails and emits a test failure.
+/// - Parameter message: An optional message to use in the failure if the
+///   assertion fails. If no message is supplied a default message is used.
+/// - Parameter file: The file name to use in the error message if the assertion
+///   fails. Default is the file containing the call to this function. It is
+///   rare to provide this parameter when calling this function.
+/// - Parameter line: The line number to use in the error message if the
+///   assertion fails. Default is the line number of the call to this function
+///   in the calling file. It is rare to provide this parameter when calling
+///   this function.
+///
+/// - Note: It is rare to provide the `file` and `line` parameters when calling
+///   this function, although you may consider doing so when creating your own
+///   assertion functions. For example, consider the following custom assertion:
+///
+///   ```
+///   // AssertEmpty.swift
+///
+///   func AssertEmpty<T>(elements: [T]) {
+///       XCTAssertEqual(elements.count, 0, "Array is not empty")
+///   }
+///   ```
+///
+///  Calling this assertion will cause XCTest to report the failure occured
+///  in the file where `AssertEmpty()` is defined, and on the line where
+///  `XCTAssertEqual` is called from within that function:
+///
+///  ```
+///  // MyFile.swift
+///
+///  AssertEmpty([1, 2, 3]) // Emits "AssertEmpty.swift:3: error: ..."
+///  ```
+///
+///  To have XCTest properly report the file and line where the assertion
+///  failed, you may specify the file and line yourself:
+///
+///  ```
+///  // AssertEmpty.swift
+///
+///  func AssertEmpty<T>(elements: [T], file: StaticString = __FILE__, line: UInt = __LINE__) {
+///      XCTAssertEqual(elements.count, 0, "Array is not empty", file: file, line: line)
+///  }
+///  ```
+///
+///  Now calling failures in `AssertEmpty` will be reported in the file and on
+///  the line that the assert function is *called*, not where it is defined.
 public func XCTAssert(@autoclosure expression: () -> BooleanType, _ message: String = "", file: StaticString = __FILE__, line: UInt = __LINE__) {
     if !expression().boolValue {
         if let test = XCTCurrentTestCase {