In the world of IT, it’s said that some documentation is better than no documentation. While that’s true, you can still encounter quite a lot of difficulties when working with any given documentation. That’s why a tool named Jazzy exists. Jazzy is a tool that can generate documentation with a single command. It saves you time and gets rid of the need for lengthy “rewrites” of the code for people who want to understand it. Let’s have a look at how this handy tool works.
Jazzy takes care of all your software documentation needs
Disclaimer: The following message is a nightmare for any developer.
You’ll now be reading hundreds of lines of code for several hours to actually understand what the tool is for. Fortunately, thanks to Jazzy, you can avoid such situations. You’ll make the lives of other people implementing your solution way easier. And you don’t even have to invest time creating external documentation for a third party framework.
What’s it all about?
Jazzy is a tool for iOS. It uses comments, called docstrings, in the source code to create documentation. And this format matches the so-called Quick Help Documentation format. To create such comments, you can use the Command + Control + / shortcut that will generate the basic structure, which can be updated with more info.
While writing the source code, one usually comments on the code, so your developer doesn’t have to do any unnecessary tasks. If the source code is correctly documented, you only have to enter the jazzy keyword from the terminal interface, and the documentation is generated, based on the default settings.
ACL generation
If you are creating a library or a framework, you define the interface the developers will use. In such a case, the project is divided into public and private parts. Of course, the public part has to be fully documented. But what about the private part? Should it be commented or not? Well, the decision is up to the team. If you assume that the framework will be developed further by someone else, it’s suitable to comment also on the private functions and variables.
Jazzy, by default, generates the documentation for public and higher ACL (Access Control Layer). While using the command jazzy for generation, you can specify the ACL level for which the documentation will be created. If you want to create documentation also for private parts, just use the command jazzy –min-acl private.
Documentation structure and output formats
By default, the documentation structure follows the object modifiers, e.g. Classes, Structures, Enums, Protocols, and so on. You can also create your own structure, e.g. if you’re creating a library with UI components and want your own structure with Buttons or Labels. The output can be generated in three different formats – Apple, Jony, and Fullwidth. Apple is set as the default format. The documentation in its default format looks like this:
Jazzy is a useful tool that can save you a lot of time and nerves. So, make your work easy and jazzy!
Lukáš Šanda
