AppCode
 
2022.2
Shortcuts: macOS
Get AppCode
You are viewing the documentation for an earlier version of AppCode.
  1. Work with source code
  2. Documenting code

Documenting code

Last modified: 19 January 2022

You can document your Swift and Objective-C code by adding documentation comments before the declarations of the symbols that you want to describe. Documentation comments use special syntax that make them different from the simple line // and block /*...*/ comments:

/// Line documentation comment

/**
* Block documentation comment
*/

/*!
* HeaderDoc-style comment (Objective-C only)
*/

Documentation provided in these comments can be viewed in the Quick Documentation popup (⌃ Q).

Generate documentation comments

In AppCode, you can generate documentation stubs for methods and functions. Generated comments will include the list of all available parameters and the Returns and Throws keywords if a method or function returns or throws anything.

Comments generated by AppCode use the Markdown formatting in Swift and the Javadoc like markup in Objective-C.

View documentation

Content of the comments becomes the documentation that you can view in the IDE.

Refactoring

While renaming a function or its parameters, the documentation comments need to be updated accordingly. After renaming (⇧ F6) parameters of a method or function, AppCode will also update all the references in documentation comments:

https://resources.jetbrains.com/help/img/idea/2022.2/ac_rename_comments.png
Gif

With the Change signature refactoring, you can add, delete, rename, or replace function/method parameters. The changes will be applied to the documentation comments as well:

https://resources.jetbrains.com/help/img/idea/2022.2/ac_change_signature_in_comments.png
Gif

Typing assistance

Basic typing assistance for documentation comments is provisioned by AppCode auto-complete feature:

Autocomplete comments

Rendered view for documentation comments

With AppCode, documentation comments can be shown in an easier-to-read format. In this Rendered View mode, items are shown grouped by their tags, while the tags themselves are skipped.

https://resources.jetbrains.com/help/img/idea/2022.2/ac_toggle_rendered_view.png
Gif

Toggle and configure the rendered view

  • To enter the Rendered View mode, hover the mouse pointer over a comment and click the Toggle Rendered View icon in the gutter or press ⌃ ⌥ Q. The icon turns into the Toggle Rendered View icon.

  • To quit the Rendered View mode, click the Toggle Rendered View icon in the gutter, or select Toggle Rendered View from the context menu of a documentation comment, or press ⌃ ⌥ Q.

  • To turn on the Rendered View mode for all documentation comments in the current file, select Render All Doc Comments from the context menu in the gutter.

    Enabling rendered view for all documentation comments

  • If necessary, select Adjust Font Size from the context menu and change the font size using the slider.

    https://resources.jetbrains.com/help/img/idea/2022.2/ac_comments_render_adjustfont.png
    Gif

  • To show all documentation comments rendered by default, open the Preferences dialog (⌃ ⌥ S), go to Editor | General | Appearance, and select the Render documentation comments checkbox.

    Turn on Rendered documentation comments by default

  • To hide the Rendered View gutter icons, select Configure Gutter Icons from the context menu in the gutter and then clear the Documentation comments in-place rendering checkbox on the Preferences | Editor | General | Gutter Icons page that opens.

See also

Procedures