Marco Eidinger
Swifty Tech by Marco Eidinger

Follow

Swifty Tech by Marco Eidinger

Follow
The visual reference guide for documenting your Swift code

The visual reference guide for documenting your Swift code

Marco Eidinger's photo
Marco Eidinger
·Feb 27, 2023·

6 min read

Table of contents

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
LinksYesYes
ImagesYesNo
TablesYesYes

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.

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.

OrderNameComment
1.Summary
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

but custom sections won't be rendered by Xcode Quick Help 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

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:

TypeUsage
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](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

    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

    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

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

Markdown

Documentation Code => Rendered Doc-C documentation

Callouts

Documentation Code => Rendered DocC documentation

Did you find this article valuable?

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

See recent sponsors Learn more about Hashnode Sponsors
 
Share this