How to create rich and engaging documents like Apple in xcode

Create documentation from our in-source comments, and add a documentation catalog to your project to provide additional content.

A common characteristic of a well-crafted Framework Code is that it’s easy to read and practically self-documenting. However, a source code alone can’t convey important information like clear documentation does. So In this post let’s try to understand the basic concept of Documenting a Swift Framework or Package.

Setup : Let’s do the setup first

Setup the documentation catalog while creation of a new swift framework

We can include a documentation catalog while creating a new Swift framework project by selecting the Include Documentation option.

Setup the documentation catalog to an existing project

1. In Xcode, select your project or package in the Project navigator.
2. Choose File > New > File to open the file template chooser.
3. Select the Documentation Catalog template in the Documentation section and click Next. Xcode creates a new catalog with a default name, which you can rename.

For Swift packages, place the documentation catalog in the same folder as your library’s source files for DocC to associate the catalog with the library.

Build Documentation : Now Let’s build it

Now when we Build Documentation we will see document

1. Choose Product > Build Documentation

Here I have created a sample framework “FeedFramework” for this post.

We can get this sample code on GitHub.

GitHub - singh46/DocumentationInSwift: Sample Framework to demonstrate documentation in Swift

Description : Let’s understand it in detail

Now let’s take an example code

Here we have written a function with comments

When we click on “Show Quick Help” we will see the details like above.

And when we create a document we will see the details like above.

Now let’ understand the basic components of above document.

• Summary : The first step towards writing a great documentation is to add single-sentence abstracts or summaries.
• Declaration : Declaration gets generated from the code itself.
• Return Value : This section contains a single list item that includes the Returns keyword.
• Parameters : This section begins with a single list item that contains the Parameters keyword and terminates with a colon (:).
• Discussion : When we want to provide additional content for a symbol, add one or more paragraphs directly below a symbol’s summary to create a discussion section.

We can enhance our content’s presentation with special formatting and styling for text, links, and other page elements. Markup Functionality will help in this.

Let’s looks at some markup functionality:

Bulleted list : Groups items that can appear in any order.
Numbered list : Delineates a sequence of events in a particular order.
Term list : Defines a series of term-definition pairs.

Symbol : Links to a symbol’s reference page in your documentation.
Article : Links to an article or API collection in your documentation catalog.
Tutorial : Links to a tutorial in your documentation catalog.
Web : Links to an external URL.

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.

Similarly we have a lot of other options, we can checkout “Markups” class :

DocumentationInSwift/Markups.swift at main · singh46/DocumentationInSwift

Till now we have seen that by using the Swift Markup and Markdown Comments we can easily document our code and add xcode Quick Help to our Swift framework project.

The above documentation helps us to describe how a specific code works, but it will not be able to explain how all the pieces in the project fit together at a conceptual level.

For this xcode provides “articles” and “extension” files.

Articles are markup files which contains information that doesn’t relate to a specific symbol.

Use articles to:

• Provide a landing page that includes an overview of your package or framework
• Craft a learning path for readers to understand how to use your project, such as with a getting started guide or a tutorial

Extension files are markup files that complement source documentation comments.

Use extension files to:

• Organize properties and methods that a symbol contains
• Provide additional content beyond source documentation comments
• Override source documentation comments

Checkout more details about articles and extension in Git code

DocumentationInSwift/FeedFramework/FeedFramework.docc at main · singh46/DocumentationInSwift

Summary :

By using Swift Markup and Markdown Comments we can easily document our code and using Articles and Extension we can add conceptual content.

Thank you for reading!