Brag how good your Swift frameworks are documented

Photo by Sigmund on Unsplash

Brag how good your Swift frameworks are documented


1 min read

Framework developers need to ensure to document the public APIs of their frameworks. Ideally you advertise the documentation status in your project's README.

I got the following question because I showed the documentation status in one of my open-source projects (SwiftPlantUML):

Sorry to bother with a question not directly related to the project, but how do you get the percentage on your documentation badge (at the is it generated by jazzy? is it a real calculated value or is it hardcoded? I could not find where it was calculated.

Screenshot 2022-05-05 at 13 08 45

I highly recommend Jazzy, a command-line utility that generates documentation for Swift or Objective-C based on your Markdown comments.

Jazzy automatically generates

  • undocumented.json listing all types that are undocumented
  • badge.svg showing the documentation coverage and perfect to include in your README
  • coverage (%) information in the index.html of the generated documentation

If you do not want the status information in the HTML page then you can suppress this with one of two options:

  1. command-line option --[no-]hide-documentation-coverage
  2. in your projectโ€™s configuration file .jazzy.yaml

    hide_documentation_coverage: true

You can add the generated badge to your README with Markdown. Example below:

Markdown codeResult