AppCode Tips & Tricks

Writing Code Documentation in AppCode

Code documentation can save you a lot of time and headaches. On the other hand, it also takes a lot of effort to write and maintain it. In this article, we will look at the AppCode features that can help you create detailed and well-structured code documentation and keep it updated after code refactorings.

The features that we will describe here are available for Objective-C and Swift. Install AppCode 2021.3 to get the full Swift documentation support.

Documentation comments

To add simple notes to your code, you can use line (⌘/) and block (⌥⌘/) comments:

Line comment

However, these comments are not supposed to be used for documentation purposes. This is how you would usually mark code that shouldn’t compile:

Block comment

To achieve consistent descriptions of classes, methods, and properties, you can use documentation comments (doc comments). Doc comments have special syntax. In Swift, there are two possible ways to use them:

Documentation comments syntax

Generate documentation comments

In AppCode, you can generate doc comments quickly: just type /// or /**, depending on the syntax you want to use, and press :

Generate documentation comments

Doc comments should precede the declaration of a code element that you want to describe. The content of the comment becomes the documentation that pops up on mouse hover or on pressing F1:

Code documentation in a popup

When adding a doc comment for a method or function, AppCode generates documentation stubs containing all available parameters and the Returns and Throws keywords if the function/method throws or returns anything:

Generate documentation for a method

Format documentation comments

Text inside the comments can be formatted using the standard Markdown syntax. You can add links, highlight text in bold and italics, add headers, and more:

Markdown formatting in documentation comments

In addition to the standard markup, you can use documentation-specific keywords, such as Warning, Note, Version, See Also, and others. Just type -, and AppCode will show you all the possible options:

Documentation key words

You can also change the style of the documentation comments. Go to Preferences | Editor | Color Schemes | Swift and adjust colors and effects for tags, values, and text under the corresponding nodes:

Formatting documentation comments

Refactorings in code documentation

AppCode helps you keep code documentation up to date after changing a method/function signature. For example, when you are renaming parameters of a method using the Rename refactoring (⇧F6), the parameter names change in the comments as well:

Rename parameters

Similarly, the Change Signature refactoring (⌘F6) affects the comments when you add or remove parameters or change their order:

Change signature

Rendered view

You can view doc comments in an easier-to-read format. Just click the icon in the gutter to switch between rendered view and edit mode:

Rendered view

All doc comments in read-only library files are displayed in rendered format by default. You can disable Reader Mode in the top right corner of the editor to show the comments as code:

Reader mode

Summary

We hope that AppCode’s code generation, auto-completion, and refactoring features that we described here will encourage you to create detailed and consistent code documentation.

For more information on code documentation support, refer to our web help.

image description