Meet DocC documentation in Xcode

Description: Discover how you can use DocC to build and share documentation for Swift packages and frameworks. We’ll show you how to begin generating documentation from your own code — or from third-party code you depend upon — and write and format it using Markdown. And we’ll also take you through the export process, helping you generate DocC archives to share with the public.

This documentation lives right alongside the platform libraries in the Developer Documentation window right in Xcode.

  • Allows to write code reference docs
  • Two additional ways to write documentation with DocC, articles and tutorials:
    • Articles allow you to walk users through the big picture behind your framework
    • tutorials are a powerful step-by-step walk-through of writing a project that uses your framework
  • Will be released as open source later this year
  • How documentation gets built:
    • Xcode builds your framework or package and asks the compiler to save information about its public APIs alongside your compiled artifacts
    • That public API information is then handed to DocC, which then combines it with your documentation catalog containing articles and tutorials written outside your source code to create the final archive containing the compiled documentation
  • Three ways for building documentation for Swift frameworks and packages in Xcode 13:
    1. to build documentation on demand, there's a new Build Documentation menu item to compile and load up your docs.
    2. if you're working on a Swift framework and always want to preview your documentation as you go, there's also a new Build Documentation during ‘Build’ build setting to build docs every time you compile
    3. via $ xcodebuild docbuild
  • Xcode supports opening the DocC Archive in a nice GUI with navigation & search (called Documentation Viewer)
  • Documentation is written in-source, via /// doc comments
  • DocC only generates documentation for code marked as public or open
  • Code examples can be added via Markdown code syntax via 3 backticks "```swift"
  • New “Open in Developer Documentation” link in any QuickHelp menu (Option + Click)
  • Prefer Parameters over Parameter for multiple parameters for method docs
  • Option+Click and choose “Add Documentation” to auto-generate documentation template
  • New double-backtick syntax to inter-link between different documented elements
  • For fields of different types, use / as in Habitat/child, includes auto-completion
  • Xcode exports an archive which is a "single page web app", can be shared to Web easily
  • Export via (…) menu, file extension is .doccarchive

Link symbols

  • You write links via a double backtick syntax
  • linking to sibling definitions only requires the name of the definition
/// This is a sibling property link ``propertyName``.
  • when referencing external definitions, we need to further qualify the link with the parent type.
/// This is a property of another type link ``TypeName/propertyName``.

Part of this note was originally published at www.notion.so.

Missing anything? Corrections? Contributions are welcome 😃

Related

Written by

Cihat Gündüz

Cihat Gündüz

Native iOS & Android developer who loves to share reusable work, like BartyCrouch, AnyLint, HandySwift & more. Founder of Flinesoft, an app company preparing for a "better future".

Federico Zanetello

Federico Zanetello

iOS Engineer with strong passion for Swift, minimalism, and design. When he’s not busy automating things, he can be found writing at FIVE STARS and/or playing with the latest shiny toys.