Swift: Deconstruct SPF: Documentation

Hi,

I have been working on this project on and off for a bit now. So I thought it was time to go over how we might be able to not only internally document our code, but also to document it at the package level.

References

• sarunw - Swift Documentation
• nshipster - Swift Documentation
• GitHub - Swift-doc
• Heartbeat - Hosting Documentation on GitHub
• Run a Local Server

Some basics

Code commenting

// denotes a single line code comment.

Package level

/// Single line Package comment.

/**
Multi-line Comments.
Are written subString
*/

I would refer you to the sarunw link above for a good and far more in depth write up.

Getting to the documentation with in Xcode

This can simply be done by hovering your mouse over the function declaration and clicking while holding down the ⌥(Option Key)

Example

This produces the following popup.

Generating Documentation that can be hosted.

There are a few options for this.

1. Jazzy
2. Anarchy Sphinx
3. Swift-doc

I chose to go with Swift-doc since it can be installed using homebrew.

At present I do not need to host any documentation. Therefore I will not be going through that process here today.

Installation

$ brew install swiftdocorg/formulae/swift-doc

Build the Documentation

From the top level of your project run the following command.

swift doc generate ./Sources/ --module-name <My Module Name> --format html

If you have no public declarations. You can run this modified command.

swift doc generate ./Sources/ --module-name <My Module Name> --format html --minimum-access-level internal

This will generate your html pages in the directory .build/documentation in your projects parent directory.

Viewing the pages.

If you have Python2 installed, using a terminal. Navigate to your projects parent directory.

cd .build/documentation
python -m SimpleHTTPServer 8000

If you are looking for other options, see the link above Run a Local Server for some ideas.

Then simple open your browser at localhost:8000

Main page


Mechanism Page

GitHub

Swift-Doc already provides a Github Action that you can add to your repo. So go check it out in the links above.

Closing

Thanks for reading.