Documenting your code is an important part of development. Code documentation regards a structured way to write comments using special keywords, also named tags, and marking the comments area with special characters, so the compiler perfectly understands it. Many developers overlook or ignore the importance of the code documentation, and that’s really bad, as good software is not just good code. It’s more than that. So today  I am going to show different ways of creating documentation of your code.

With the introduction of Xcode 7, developers can use the powerful Markdown syntax to apply rich text formatting to the text of their documentation. Proper code documentation enables you to produce complete HTML documentation for your app using various tools, such as the HeaderDoc and Doxygen.

Comments

There are 2 ways to create comments in swift

1. Single Line Comment (\\).
2. Multi-Line Comment (/* ... */).

Documentation

Documentation comments look like normal comments, but they come with some extra features. You can write documentation comments in 2 ways:

1. Single-line documentation comments have three slashes (\\).
2. Multi-line documentation comments have an extra star in their opening delimiter (/** ... */).

Below is an example of how to create a basic documentation comment.

Swift provides many ways to auto-generate documentation structure for your code.

1. Press  Command + Option + / inside the and it will automatically create a structure for your documentation.
2. Select Method go to Editor menu then structure and select Add Documentation

MARK / TODO / FIXME

In Objective-C, the pre-processor directive #pragma mark  is used to divide functionality into meaningful, easy-to-navigate sections. In Swift, there are no pre-processor directives, but the same can be accomplished with the comment // MARK:

• // MARK: (As with #pragma, marks followed by a single dash (-) are preceded with a horizontal divider) 
• // TODO:
• // FIXME:

Markdown

Standard Markdown rules apply inside documentation comments.

• Paragraphs are separated by blank lines.
• Unordered lists are marked by bullet characters (-, +, *, or •).
• Ordered lists use numerals (1, 2, 3, …) followed by either a period (1.) or a right parenthesis (1)).
• Headers are preceded by # signs or underlined with = or -.

The leading paragraph of a documentation comment becomes the documentation Summary. Any additional content is grouped together into the Discussion section.

Xcode recognizes a few special fields and makes them separate from a symbol’s description. Below is the list of these fields:

Parameters & Return Values

The parameters, return value and throws sections are broken out in the Quick Help pop over and inspector when styled as a bulleted item followed by a colon (:).

• Parameters: Start the line with Parameter <param name>: and the description of the parameter.
• Return values: Start the line with Returns: and information about the return value.
• Thrown errors: Start the line with Throws: and a description of the errors that can be thrown. Since Swift doesn’t type-check thrown errors beyond Error conformance, it’s especially important to document errors properly.

Below I have attached the sample of proper documentation of code looks like.

Thank you