Swift Documentation Markup

by Erica Sadun

No matter how clear and well written, naked code is never quite self-documenting. There is always a role for comments, whether the in-line narration of key design points or the formal annotation of public declarations. Nearly every modern language, including Swift, offers some kind of structured comment system that documents APIs for developers that consume them.

This short book introduces Swift’s documentation markup system using simple, illustrated examples, with plenty of discussion of best practices. You’ll discover the components that make up Swift’s structured comment system and learn how to best integrate them into your own code.

I’ve built this material out of examples from Swift’s standard library, from release notes, and by reverse-engineering extensible style-sheet specifications. I’ve supplemented core details with a thoughtful discussion of best practices that should stand the test of time as Apple updates this currently undocumented system.

ebook

Published October 15, 2015

Reviews

[Michael Stanziano · Rating 4 out of 5]

While short, this was a really well put together collection of information otherwise tough to get all at once. Felt like reading a blog post (or a series of blog posts).