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" (⌥⌘/)

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.

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.

      ![Docc](docc.png)

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

     */
    public func image() {}

Local images and web images will not be rendered in Xcode Quick Help.

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:

• Documentation Code

• Rendered Doc-C documentation

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.

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

but custom sections won't be rendered by Xcode Quick Help compared to DocC ...

or Jazzy.

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

Callouts

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:

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

• Complexity

• Copyright

• Todo,

• Version

• ...

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:

• Documentation Code

• Rendered DocC documentation

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

• Documentation Code

• Rendered DocC documentation

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

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](https://www.google.com)   |
     | **bold**       | *italic*   |
     | `codeVoice` |  ``Callouts``  |

    ```swift
    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

  

  • Parameters:
• file: URL

• directory: in which the file is located

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

  Custom Callout: Hello :)

  Custom Section

  Hello

  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

Visualization by DocC Renderer

Live Doc-C documentation

Individual examples

Markdown

Documentation Code => Rendered Doc-C documentation

Callouts

Documentation Code => Rendered DocC documentation