Swift: Deconstruct SPF: Documentation
Tags: swift, beginners, documentation, package
Published: 2021-06-04 08:14:48


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](https://sarunw.com/posts/swift-documentation/)
- [nshipster - Swift Documentation](https://nshipster.com/swift-documentation/)
- [GitHub - Swift-doc](https://github.com/SwiftDocOrg/swift-doc)
- [Heartbeat - Hosting Documentation on GitHub](https://heartbeat.fritz.ai/generating-docs-for-your-swift-package-and-hosting-on-github-pages-2786b8ce28d)
- [Run a Local Server](https://css-tricks.com/snippets/html/start-a-web-server-with-one-terminal-command-on-os-x/)


## Some basics

### Code commenting
```text
// denotes a single line code comment.
```

### Package level
```text
/// Single line Package comment.
```

```text
/**
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
![Swift code Comment](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/hqca5wul2up9gkdjb9e6.png)
This produces the following popup.  
![Swift Documentation Popup](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/arzx9anw8gva2sbbe2sh.png)

## Generating Documentation that can be hosted.

There are a few options for this.
1. [Jazzy](https://github.com/realm/jazzy)
2. [Anarchy Sphinx](https://github.com/AnarchyTools/anarchy_sphinx)
3. [Swift-doc](https://github.com/SwiftDocOrg/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
```bash
$ brew install swiftdocorg/formulae/swift-doc
```

### Build the Documentation
From the top level of your project run the following command.
```bash
swift doc generate ./Sources/ --module-name <My Module Name> --format html
```

If you have no public declarations. You can run this modified command.
```bash
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.
```bash
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  
![Swift Doc1](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/yb6yjz268n9hqrpntk31.png)
Mechanism Page  
![Swift Doc2](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/k9vf5797h9k5f0jlcvv3.png)
### 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.