Marco Eidinger
Swifty Tech by Marco Eidinger

Swifty Tech by Marco Eidinger

Brag how good your Swift frameworks are documented

Photo by Sigmund on Unsplash

Brag how good your Swift frameworks are documented

Marco Eidinger's photo
Marco Eidinger
·May 5, 2022·

1 min read

Subscribe to my newsletter and never miss my upcoming articles

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 README.md)? 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
[![docs](https://marcoeidinger.github.io/SwiftPlantUML/badge.svg)](https://marcoeidinger.github.io/SwiftPlantUML/)docs
 
Share this