{"id":225037,"date":"2022-02-15T14:26:00","date_gmt":"2022-02-15T13:26:00","guid":{"rendered":"https:\/\/blog.jetbrains.com\/?post_type=objc&p=225037"},"modified":"2022-08-09T16:42:51","modified_gmt":"2022-08-09T15:42:51","slug":"writing-code-documentation-in-appcode","status":"publish","type":"appcode","link":"https:\/\/blog.jetbrains.com\/fr\/appcode\/2022\/02\/writing-code-documentation-in-appcode","title":{"rendered":"Writing Code Documentation in AppCode"},"content":{"rendered":"

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.<\/p>\n

The features that we will describe here are available for Objective-C and Swift. Install AppCode 2021.3<\/a> to get the full Swift documentation support.<\/p>\n

Documentation comments<\/h1>\n

To add simple notes to your code, you can use line (\u2318\/<\/code>) and block (\u2325\u2318\/<\/code>) comments:<\/p>\n

\"Line<\/p>\n

However, these comments are not supposed to be used for documentation purposes. This is how you would usually mark code that shouldn\u2019t compile:<\/p>\n

\"Block<\/p>\n

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

\"Documentation<\/p>\n

Generate documentation comments<\/h1>\n

In AppCode, you can generate doc comments quickly: just type \/\/\/<\/code> or \/**<\/code>, depending on the syntax you want to use, and press <\/code>\u23ce<\/code>:<\/p>\n

\"Generate<\/p>\n

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>:<\/p>\n

\"Code<\/p>\n

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

\"Generate<\/p>\n

Format documentation comments<\/h1>\n

Text inside the comments can be formatted using the standard Markdown syntax<\/a>. You can add links, highlight text in bold and italics, add headers, and more:<\/p>\n

\"Markdown<\/p>\n

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

\"Documentation<\/p>\n

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

\"Formatting<\/p>\n

Refactorings in code documentation<\/h1>\n

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<\/strong> refactoring (\u21e7F6<\/code>), the parameter names change in the comments as well:<\/p>\n

\"Rename<\/p>\n

Similarly, the Change Signature<\/strong> refactoring (\u2318F6<\/code>) affects the comments when you add or remove parameters or change their order:<\/p>\n

\"Change<\/p>\n

Rendered view<\/h1>\n

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:<\/p>\n

\"Rendered<\/p>\n

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

\"Reader<\/p>\n

Summary<\/h1>\n

We hope that AppCode\u2019s code generation, auto-completion, and refactoring features that we described here will encourage you to create detailed and consistent code documentation.<\/p>\n

For more information on code documentation support, refer to our web help<\/a>.<\/p>\n","protected":false},"author":1139,"featured_media":0,"comment_status":"closed","ping_status":"closed","template":"","categories":[4244,601],"tags":[6935,6936,1445,6937],"cross-post-tag":[],"acf":[],"_links":{"self":[{"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/appcode\/225037"}],"collection":[{"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/appcode"}],"about":[{"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/types\/appcode"}],"author":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/users\/1139"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/comments?post=225037"}],"version-history":[{"count":4,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/appcode\/225037\/revisions"}],"predecessor-version":[{"id":228269,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/appcode\/225037\/revisions\/228269"}],"wp:attachment":[{"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/media?parent=225037"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/categories?post=225037"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/tags?post=225037"},{"taxonomy":"cross-post-tag","embeddable":true,"href":"https:\/\/blog.jetbrains.com\/fr\/wp-json\/wp\/v2\/cross-post-tag?post=225037"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}