Brag how good your Swift frameworks are documented

Photo by Sigmund on Unsplash

Brag how good your Swift frameworks are documented

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