The visual reference guide for documenting your Swift code

The visual reference guide for documenting your Swift code

Updated for Xcode 15

In this blog post, I provide a complete overview of markdown and callout options to document your Swift code.

I also share tips and tricks to create documentation efficiently, as well as highlight differences in how documentation is rendered by Xcode Quick Help vs DocC Renderer vs. Jazzy.

Use Xcode's "Add documentation" option

How to get started?

public func megaMarkupExample(for file: URL, in directory: URL) throws -> String { "missing Documentation :(" }

Xcode provides a convenient way to "Add Documentation" (⌥⌘/)

Add Documentation option in Xcode

Xcode will add single-line comments (///), but I prefer the block comment notation.

   A summary of the documentation
   - Parameters:
     - file: file description
     - directory: directory description
   - Throws: description
   - Returns: description

Format with Markdown

You can use traditional markdown notation to format your code.

TypeVisualization by DocC RendererVisualization by Xcode Quick Help
bold textYesYes
italic textYesYes
Code Voice textYesYes
Code BlockYesYes
Code ReferenceYesYes
Bulleted ListsYesYes
Numbered ListsYesYes
ImagesYesXcode 15+

You must store local images in your documentation catalog (.docc) to be rendered.

      An example of using *images* to display a local image.

      You must store images you include in your documentation in a documentation catalog.


     - Important: Not visible in Xcode Quick Help but in DocC generated documentation.

    public func image() {}

Local images and web images will be rendered in Quick Help staring with Xcode 15. Older Xcode versions do not render images as seen below.

Images are not rendered in Xcode Quick Help

Images are rendered by DocC

Apple has a well-written Formatting your documentation content article explaining the basics.

But I also recommend you have a look at the individual examples I provide:

Anatomy of symbol documentation

I will talk about the documentation structure for a function/property. If you are more interested in configuring a landing page (for a framework or type), then please read the following:

The symbol documentation is grouped into sections.

2.Declarationgenerated automatically
3.Discussioncan include markdown-formatted text & Callouts
4.Parametersoptional; lists the parameters for a method or function; will automatically be added when using "Add Documentation"(⌥⌘/) option in Xcode
5.Returnsoptional; will automatically be added when using "Add Documentation" (⌥⌘/) option in Xcode
6.<Custom Sections>optional; multiple possible; can be added with headlines (X)

Custom Sections can be defined with a heading (e.g. # This is a Heading 1)

Xcode Quick Help does not render custom sections unless you use Xcode 15

Xcode 15 will render custom sections in the Quick Help but older Xcode versions won't show custom sections compared to DocC ...

DocC renders custom sections

or Jazzy.

Jazzy renderes custom sections

Important to know is some delimiters create a new section, but most delimiters create a callout box in the Discussion section.

  • Delimiters creating a section: - Parameters: or - Returns:

  • Delimiters creating a callout: - Throws: and many more


Call-out boxes (a.k.a asides in DocC) were an early concept in the Xcode Markup Reference and were defined with a dash (-), e.g. Note: some note.

DocC promotes the following callouts:

NoteGeneral information that applies to some users.
ImportantImportant information, such as a requirement.
WarningCritical information, like potential data loss or an irrecoverable state.
TipHelpful information, such as shortcuts, suggestions, or hints.
ExperimentInstructional information to reinforce a learning objective, or to encourage developers to try out different parts of your framework.

Example for Note callout

Example for Warning callout

There are plenty more built-in "legacy" callouts, e.g.

  • Complexity

  • Copyright

  • Todo,

  • Version

  • ...

Example for Complexity callout

Most of them are supported by DocC Renderer.

However, some legacy callouts are neither supported by Xcode Quick Help or DocC but might be rendered by other tools like Jazzy:

  • See Also

  • Keyword

  • Recommended

  • ...

You will find a complete list of working callout examples here:

The "not-working" examples you will find here:

Custom Callouts

For DocC you should declare a callout with >, e.g. > Note: some note.

This allows you to create custom callouts.

     create custom callouts with `>`.

     > My Custom Callout: hi :)

    public func custom() {}

Xcode Quick or Jazzy will not render custom callouts.

Reference Guide

I created a Swift code base that uses and illustrates the various Markup options to create symbol documentation.

The respective DocC-generated documentation is hosted as a static web page on GitHub and is accessible through this link.

It includes a mega example to highlight all the options.

Mega Example

Mega Example

Documentation Code

import Foundation

  This example leverages all concepts that you can use for symbol documentation

    First, content for discussion

     | Column1  | Column2                           |
     | ------------ | ----------------------------------- |
     |  Some Plain Text      | [Web Link](   |
     | **bold**       | *italic*   |
     | `codeVoice` |  ``Callouts``  |

    let codeBlock = "works"
  • version: 1.0

    Find more buid-in support for Callouts (<- code reference link)

    Next: nested lists

    1. Level 1, Item 1
      1. Level 2, Item 1
        func emptyFunc() {
      2. Level 2, Item 2
    2. Level 1, Item 2

    3. bulletListItem1

    4. bulletListItem2

    image works in DocC but not in Xcode

    • Parameters:
  • file: URL
  • directory: in which the file is located

    • Throws: sometimes
    • Returns: a String containing a complex example

    Custom Callout: Hello :)

    Custom Section


    Custom Sub Section

    • Note: This is a note

      Tip: Hope this is helpful

    */ public func megaMarkupExample(for file: URL, in directory: URL) throws -> String { "" } ```

Visualization in Xcode Quick Help

Mega Example rendered in Xcode Quick Help

Visualization by DocC Renderer

Mega Example rendered by DocC Renderer - Part 1

Mega Example rendered by DocC Renderer - Part 2

Mega Example rendered by DocC Renderer - Part 3

Live Doc-C documentation

Individual examples


Documentation Code => Rendered Doc-C documentation


Documentation Code => Rendered DocC documentation

Did you find this article valuable?

Support Marco Eidinger by becoming a sponsor. Any amount is appreciated!