Documenting the WriteFreely Swift package

Finding a tool that generates documentation from code comments has proven to be trickier than I expected.

Ideally —for me, anyhow— documentation moves with the repository, is easy to read in a text editor, and isn't tied to any specific platform.

The two big players (that I know of, at least) for generating documents from Swift files are Jazzy and SwiftDoc. Both can generate a lovely static website for your docs, which can be very helpful, but require additional tooling to deploy the HTML to a server somewhere.

SwiftDoc can also generate CommonMark Markdown files, a flavour of Markdown that many online platforms have adopted. It generates, however, a few additional files:

• Home.md, meant to be a home page linking to each documented type (more on this below)
• _Footer.md, which indicates when the documents were generated
• _Sidebar.md, which has the same links as Home.md, but in a <detail> HTML element.

What are these extra files for? They're meant for deploying to a GitHub Wiki (here's the SwiftDoc output for Alamofire, for example). That's handy, if you've committed to using GitHub as your project management hub.

If not, then the first thing you'll notice is that the links in Home.md and _Sidebar.md are broken, because they don't actually link to the files in SwiftDoc's output directory. You get a link to something like:

https://github.com/writeas/writefreely-swift/blob/main/WriteFreelyClient

when you should have something like:

https://github.com/writeas/writefreely-swift/blob/main/docs/WriteFreelyClient.md

If you're using anything other than GitHub Wikis, those files aren't very helpful. Instead, you'd probably want something like a README.md file instead of Home.md, serving links to individual files for each type (and no _Footer.md and _Sidebar.md files, of course).

I don't want to take anything away from the work put into these tools by —and for— the Swift developer community. They're still extremely useful! But the promise of Git is that it's a decentralized system for version control of your source code, not tied to any given vendor, and I just wish that the principle of documentation being as portable as the source code had been considered.

Anyhow, for now, I'm using SwiftDoc to generate a /docs folder in the repository. Once I tackle automation, I can add a pre-commit hook that removes/fixes those GitHub Wiki-specific files.

Enter your email to subscribe to updates:

You can also subscribe via RSS or follow @[email protected] on Mastodon.