Behavior validation docs

[iamleeg]

Introduces additional documentation for expectations and confirmations.

Checklist:

• Code and documentation should follow the style of the Style Guide.
• If public symbols are renamed or modified, DocC references should be updated.

[iamleeg]

@swift-ci please test

[grynspan]

Please use double-backticks and link to the expect(_:_:) macro rather than writing #expect(). Ibid for #require(), but note the overloads are different. (This is an error in the existing documentation.)

[iamleeg]

On first use only, or every time?

[grynspan]

Every time: DocC does not render macros with leading # or @ characters, so having them suddenly appear is likely to be confusing. If, later, DocC does add those characters, we'll get them everywhere "for free".

[grynspan]

However, if your department already has guidelines for this sort of thing, I defer to you.

[iamleeg]

FWIW, what a developer types is #expect() or #require(), so I think it's more helpful to show them that; nonetheless, I'll change this to match the local style.

[grynspan]

We'd much prefer the DocC compiler would add the # for us in this case. There's an issue or radar or some such floating around out there about it.

[grynspan]

There's more nuance here: a throwing test function is almost always sufficient:

@Test func f() throws {
  try g() // if this throws, the test fails
}

#expect(throws: Never.self) is useful when the potentially-throwing expression is part of a larger operation, but a thrown error should not interrupt execution. See the documentation for #expect(throws: Never.self) itself for some more discussion.

[iamleeg]

What do you think of this, is it sufficient or would an example help?

[grynspan]

We should emphasize here that a test function that throws will fail if an error is thrown, so usually you don't need to use #expect(throws: Never.self). You'd really only use it if you want to record an issue for a thrown error but not stop execution of the test function. It's pretty nuanced, to the point that I'm not sure we should even call it out in the documentation.

[grynspan]

There's some history here that we don't need to document, but for your own edification/amusement: XCTest in Objective-C has XCTAssertNoThrow() that asserts a given expression doesn't throw an Objective-C or C++ exception. This is different from a Swift error because if an exception is thrown through a test method's frame, it tends to wreak some havoc on the way out before being caught by XCTest, so you want to proactively catch them if you know they might occur. This was inherited as XCTAssertNoThrow() in Swift which checks if a function throws a Swift error rather than an exception.

[grynspan]

You have a Toppings type and a PizzaToppings type. But this type also describes the base. Perhaps this should just be Pizza and the other types should be nested Pizza.Topping and Pizza.Base?

[grynspan]

See comments above.

[chuckdude]

OK from Editorial. Looks like there are still issues to sort out with the code. If those changes affect the text, please feel free to pass this by me for another look.

[chuckdude]

All good here. Thanks.

[grynspan]

Looks good. Documentation only, so skipping CI.