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.
To add simple notes to your code, you can use line (
⌘/) and block (
However, these comments are not supposed to be used for documentation purposes. This is how you would usually mark code that shouldn’t compile:
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:
Generate documentation comments
In AppCode, you can generate doc comments quickly: just type
/**, depending on the syntax you want to use, and press
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
When adding a doc comment for a method or function, AppCode generates documentation stubs containing all available parameters and the
Throws keywords if the function/method throws or returns anything:
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:
In addition to the standard markup, you can use documentation-specific keywords, such as
See Also, and others. Just type
-, and AppCode will show you all the possible options:
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:
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:
Similarly, the Change Signature refactoring (
⌘F6) affects the comments when you add or remove parameters or change their order:
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:
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:
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.
Subscribe to Blog updates
AppCode 2022.1: Swift Support Improvements, Xcode 13.3 Support, and More
AppCode 2022.1 brings support for async sequences, postfix #if member expressions, isolation control specifiers for Swift actors, improvements for Swift Package Manager integration, better VoiceOver support, and more.
AppCode Starts 2022.1 EAP: Swift Support Improvements and Bug Fixes
Hi everyone, Today we are starting the Early Access Program for AppCode 2022.1, and the first build is already available for download. Language support Starting with this build, AppCode supports async sequences (SE-0298). Other improvements and bug fixes Separate color settings for associated …
AppCode 2021.3 Beta 2: Improved Documentation Support and Bug Fixes
Hi everyone, The new AppCode 2021.3 Beta 2 is available for download from our site. Documentation Now you can specify separate colors for tags, their values, and regular text in Swift documentation comments: AppCode will update your documentation when performing refactorings: In addition, you…