Amongst all the features Xcode 7 incorporates, there is one that admittedly distinguishes; that is the new revolutionary, much better way to write code documentation. With the introduction of Xcode 7, developers can use the powerful Markdown syntax to apply rich text formatting to the text of their documentation, which in combination to specific keywords that indicate special parts (like parameters, function results, etc) can result to an amazing outcome. The new Markdown-enabled documentation style, as the new one has several advantages: It provides greater level for customizing the text, it’s more flexible, and of course, more interesting. However, if you’re still interested in the old-style documenting style, take a look in our previous tutorial.
Documenting the code is an extremely important task for every developer. Even though it seems that it stalls the development process, it’s actually a part of it. I won’t disagree that writing proper and comprehensive documentation for every single property, function, class, struct, or anything else that exists in a project is not an easy job. However by writing the proper documentation you can:
- Describe the purpose of the properties, functions and classes up to the level of detail that you desire. Moreover, it’s the best place to highlight specific conditions, cases or requirements for your functions that have to be noted somewhere.
- Highlight the input and output (parameters and return values) of your methods.
- Remember without any hassle what each function is meant to do and what each property is for when you revisit a project months after its initial implementation.
- Make it easy for other developers to understand how to use your code when you share it or make your own libraries.
- Produce professional-looking manuals using tools made for this reason (for example Jazzy).
The code documentation you write in Xcode can be previewed and accessed in three different ways:
- By Option/Alt-Clicking to the name of a property, method, class, etc. The Quick Look preview will pop up right above or below the name.
- By placing the cursor in the property, method or class name, and opening the Quick Help Inspector.
- By using third-party tools that will produce a manual for you. For example, Jazzy is such a tool, and we’ll discuss about it later on. By using it, your documentation is compiled in webpages and all together consist of a standalone website that is being created as a subfolder inside your project’s folder.
Code documentation is not made of stone; it has to be fluid and change according to modifications being made in the respective entities (properties, methods, classes, structs, enums). It’s almost a rule that if you don’t add the documentation by the time of the implementation of a new entity, then it’s almost certain that you’ll never do it. Therefore, try to get used to the habit of documenting your code in the proper timing, and give it any additional time it requires so you make it proper. It worths it.