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.
This can simply be done by hovering your mouse over the function declaration and clicking while holding down the
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
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.
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.
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.