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.
- sarunw - Swift Documentation
- nshipster - Swift Documentation
- GitHub - Swift-doc
- Heartbeat - Hosting Documentation on GitHub
- Run a Local Server
// denotes a single line code comment.
/// 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
This produces the following popup.
Generating Documentation that can be hosted.
There are a few options for this.
I chose to go with Swift-doc since it can be installed using
At present I do not need to host any documentation. Therefore I will not be going through that process here today.
$ 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
Swift-Doc already provides a Github Action that you can add to your repo. So go check it out in the links above.
Thanks for reading.