[XCTAssert] Document usage of file and line params

Although it is rare for people to specify these parameters manually, it
is not so rare as to not require documentation. Add a note to the
documentation that explains when they are useful.

Also adopt documentation conventions from the Swift standard library:
use `///` over `/** */`, and only have 80 characters per line.

Author: modocache

XCTest/XCTAssert.swift

@@ -10,13 +10,58 @@
 //  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.
+///
+/// - 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 {