# The visual reference guide for documenting your Swift code 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? ```swift 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](https://cdn.hashnode.com/res/hashnode/image/upload/v1677435517388/0ea75bec-c46c-446b-8b7c-61ef94b534f7.gif align="center") Xcode will add single-line comments (`///`), but I prefer the block comment notation. ```swift /** 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. | Type | Visualization by DocC Renderer | Visualization by Xcode Quick Help | | --- | --- | --- | | **bold** text | Yes | Yes | | *italic* text | Yes | Yes | | `Code Voice` text | Yes | Yes | | Code Block | Yes | Yes | | Code Reference | Yes | Yes | | Bulleted Lists | Yes | Yes | | Numbered Lists | Yes | Yes | | Links | Yes | Yes | | Images | Yes | Xcode 15+ | | Tables | Yes | Yes | You must store local images in your documentation catalog (.docc) to be rendered. ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1677485543807/a40a0f5c-7985-4d51-92f9-4e5bfc08492c.png align="center") ```swift /** 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() {} ``` ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431387822/db187a78-ef20-4360-9017-a3add8d16c07.png align="center") 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](https://cdn.hashnode.com/res/hashnode/image/upload/v1677485369547/f6e6725b-6277-4baa-b3cf-9ee98acba245.png align="center") ![Images are rendered by DocC](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431399913/c512fb4a-d4df-4c4a-9384-03f595433231.png align="center") Apple has a well-written [Formatting your documentation content](https://developer.apple.com/documentation/xcode/formatting-your-documentation-content) article explaining the basics. %[https://developer.apple.com/documentation/xcode/formatting-your-documentation-content] But I also recommend you have a look at the individual examples I provide: * [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/Basics.swift) * [Rendered Doc-C documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/basics/) ## 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: %[https://developer.apple.com/documentation/xcode/adding-structure-to-your-documentation-pages] The symbol documentation is grouped into sections. ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1677474918892/86e389cd-8586-499e-a94f-15a429d29685.png align="center") | Order | Name | Comment | | --- | --- | --- | | 1. | Summary | | | 2. | Declaration | generated automatically | | 3. | Discussion | can include markdown-formatted text & Callouts | | 4. | Parameters | optional; lists the parameters for a method or function; will automatically be added when using "Add Documentation"(`⌥⌘/`) option in Xcode | | 5. | Returns | optional; 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](https://cdn.hashnode.com/res/hashnode/image/upload/v1677494855037/d2d0d575-8592-493f-b219-29ac7917b103.png align="center") 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](https://cdn.hashnode.com/res/hashnode/image/upload/v1677494924509/0462c380-b28b-4769-bb50-593e613f2c75.png align="center") or Jazzy. ![Jazzy renderes custom sections](https://cdn.hashnode.com/res/hashnode/image/upload/v1677494944079/83db9b2f-5a1f-4293-9b34-d628408fa5a6.png align="center") 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](https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html#//apple_ref/doc/uid/TP40016497-CH2-SW1) and were defined with a dash (`-`), e.g. `Note: some note`. DocC promotes the following callouts: | Type | Usage | | --- | --- | | Note | General information that applies to some users. | | Important | Important information, such as a requirement. | | Warning | Critical information, like potential data loss or an irrecoverable state. | | Tip | Helpful information, such as shortcuts, suggestions, or hints. | | Experiment | Instructional information to reinforce a learning objective, or to encourage developers to try out different parts of your framework. | ![Example for Note callout](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431495104/c60ab575-bc4e-4162-9039-1833f53b2087.png align="center") ![Example for Warning callout](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431468593/69807199-232c-4cc7-8443-5b3085e9633a.png align="center") There are plenty more built-in "legacy" callouts, e.g. * `Complexity` * `Copyright` * `Todo`, * `Version` * ... ![Example for Complexity callout](https://cdn.hashnode.com/res/hashnode/image/upload/v1677495723594/a684e2f0-edd4-4800-9e60-ea9283b8f448.png align="center") 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](https://github.com/realm/jazzy): * `See Also` * `Keyword` * `Recommended` * ... You will find a complete list of working callout examples here: * [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/Callouts.swift) * [Rendered DocC documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/callouts) The "not-working" examples you will find here: * [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/NotWorking.swift) * [Rendered DocC documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/notworking) ### Custom Callouts For DocC you should declare a callout with `>`, e.g. `> Note: some note`. This allows you to create custom callouts. ```swift /** create custom callouts with `>`. > My Custom Callout: hi :) */ public func custom() {} ``` ![](https://cdn.hashnode.com/res/hashnode/image/upload/v1677495421398/8911061e-79e4-4cde-8c0b-caf2d7b74432.png align="center") 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. %[https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples] The respective DocC-generated documentation is hosted as a static web page on GitHub and is [accessible through this link](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples). It includes a mega example to highlight all the options. ![Mega Example](https://cdn.hashnode.com/res/hashnode/image/upload/v1677430491554/c41dda74-2666-4142-86a4-6bef006f4d4a.png align="center") ### Mega Example [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/MegaExample.swift) ```swift 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 ```swift func emptyFunc() { } ``` 1. Level 2, Item 2 1. Level 1, Item 2 - bulletListItem1 - bulletListItem2 ![image works in DocC but not in Xcode](https://upload.wikimedia.org/wikipedia/en/5/56/Xcode_14_icon.png) - 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](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431667486/f699c5aa-522a-44a9-8743-d6e82094e5cd.png align="center") ### Visualization by DocC Renderer ![Mega Example rendered by DocC Renderer - Part 1](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431439282/b47e6b90-58e0-4fc2-9488-a6a690c78d0c.png align="center") ![Mega Example rendered by DocC Renderer - Part 2](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431526547/fb372407-bee8-458f-825d-ba66141c2c45.png align="center") ![Mega Example rendered by DocC Renderer - Part 3](https://cdn.hashnode.com/res/hashnode/image/upload/v1677431556813/a59fbc1e-2178-41c2-923f-0217339c2574.png align="center") [Live Doc-C documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/megamarkupexample(for:in:)) ## Individual examples ### Markdown [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/Basics.swift) => [Rendered Doc-C documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/basics/) ### Callouts [Documentation Code](https://github.com/MarcoEidinger/SwiftSymbolDocMarkupExamples/blob/0e4c88beafa0e90b1d21df86bce16166a3050083/Sources/SwiftSymbolDocMarkupExamples/Callouts.swift) => [Rendered DocC documentation](https://marcoeidinger.github.io/SwiftSymbolDocMarkupExamples/documentation/swiftsymboldocmarkupexamples/callouts)