Apple's DocC is excellent, but unusable for open source projects · Jesse Squires

submited by

Style Pass

2021-06-30 08:00:03

I was very excited at this year’s WWDC when Apple announced DocC, their new “Documentation Compiler” tool that generates documentation from comments in your source code. Unfortunately, it’s not going to work for the majority of open source authors.

Many folks are probably unaware that the company shipped and maintained a similar tool before, the now-defunct HeaderDoc, which had a final stable release in 2009. Eventually, Tomaz Kragelj wrote and released an open source replacement called AppleDoc, which became the standard way for Apple platform developers to publish documentation for their open source libraries. While AppleDoc began to languish from a lack of regular contributors, Swift was announced in 2014. AppleDoc was soon replaced by another community-built tool, Jazzy, authored by JP Simard and maintained by various contributors. More recently, Mattt took another approach at solving this problem with swift-doc. After all these years of the open source community filling in the gaps and building their own tools, Apple finally announced a new first-party solution for generating documentation.

Overall, there are many things to like about DocC. The integration with Xcode’s Editor and Documentation Viewer is excellent. There is a command-line tool included, xcodebuild docbuild, which you can invoke from automation scripts. The overall workflow for generating and exporting documentation is built-in to Xcode and its build process, making it very easy to use. Finally, the documentation itself looks incredible. It uses the same styling as Apple’s official documentation, making it very familiar to any Apple platform developer. The design is clean and well-organized. You can even include supplemental resources, including interactive tutorials.