How to generate fabulous API reference docs for iOS

At Firebase, we were using Doxygen to generate iOS API reference docs. While it did the job for ObjectiveC, it wasn’t supporting Swift. We started using Jazzy for the look and feel of Apple’s official reference documentation. The documentation which iOS developers are used to.

jazzy is a command-line utility that generates documentation for Swift or Objective-C. It is composed of two parts:

1. The parser, SourceKitten (written in Swift)
2. The site generator (written in ruby)

It leverages

• modern HTML templating (Mustache)
• the power and accuracy of the Clang AST and SourceKit

Firebase iOS API Reference documentation

In our setup, we have a shell script. It

• simplifies jazzy setup,
• unifies through different modules we have,
• sets mustache templates.

In our first try, we were awed by the beautiful documentation right of the batch. But, we saw couple issues. These were originating because Jazzy was only accepting ObjectiveC/Swift style comments. Whereas Doxygen was supporting C++ style comments. Before diving down to each issue, let me explain how we tackled them:

1. We created a Jazzy style guide for comments for future development.
2. We used Jazzy’s--skip-documentation parameter to find out the missing or broken comments. We integrated this parameter into our script as well for due diligence.
3. We worked with engineers to update the comments into new syntax as soon as we can.
4. In the interim we created a preprocessing script. It removes unsupported keywords from our header files temporarily (just for the execution).

sed -i ‘’ -e ‘s/ * @method [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @typedef [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @class [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @fn [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @property [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ * @enum [:_.[\:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/@abstract //g’ *.h
sed -i ‘’ -e ‘s/@brief //g’ *.h
sed -i ‘’ -e ‘s/@discussion //g’ *.h
sed -i ‘’ -e ‘s/@remarks //g’ *.h
sed -i ‘’ -e ‘s/@returns/Returns/g’ *.h
sed -i ‘’ -e ‘s/ @memberof [:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/ @related[:_.[:alnum:]]*[:[:alnum:]]//g’ *.h
sed -i ‘’ -e ‘s/{@link \([:_.[:alnum:]]*[:[:alnum:]]\)}/<code>\1<\/code>/g’ *.h
sed -i ‘’ -e ‘s/@c \([:_.[:alnum:]]*[:[:alnum:]]\)/<code>\1<\/code>/g’ *.h

You can keep reading the Migration Guide from Doxygen to Jazzy.