The hardest part of software documentation is writing it in the first place. But once you clear that initial hurdle, the challenge becomes keeping doc

SwiftDocOrg / DocTest

submited by
Style Pass
2021-08-17 14:30:04

The hardest part of software documentation is writing it in the first place. But once you clear that initial hurdle, the challenge becomes keeping documentation correct and up-to-date.

There's no built-in feedback mechanism for documentation like there is for code. If you write invalid code, the compiler will tell you. If you write valid but incorrect code, your test suite will tell you. But if you write documentation with invalid or incorrect example code, you may never find out.

DocTest offers a way to annotate Swift code examples in documentation with expectations about its behavior, and test that behavior automatically — just like a unit test.

DocTest launches and interacts with the Swift REPL, passing each code statement through standard input and reading its result through standard output and/or standard error.

We can use DocTest to identify these problems automatically by adding "doctest" to the start of the fenced code block. This tells the documentation test runner to evaluate the code sample.

Leave a Comment
Related Posts