Now available on iBooks.  Sale price for first week: $4.99.

And, yes. This book does describe how to incorporate animated kitten gifs into Xcode Quick Help pop-ups.

Overview:

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.

I hope you find this book to be a useful and worthy addition to your development library. I’ve had a great time writing it. Hopefully you’ll have a great time reading it.