preface

I have been writing code for some time, and I have written various comments in the code. However, I found the problem when I was developing with my colleagues. The comments of all of us were different, and we could not write the official comments of Apple. Probably there was something wrong with the syntax of the annotation, so I took the initiative to learn the syntax format of the annotation of Swift code and recorded what I learned.

Annotation syntax

Single-line comments

// Single-line comment
Copy the code
  • Single-line comments appear primarily at the top of the.swfit file, recording some information about the code file.
  • It also appears in code to record the interpretation of a single line of code.

Single-line documentation comments

/// single-line document comment
Copy the code

When we use ⌥ + left mouse button, click on the code, you can view the documentation page of the property or method, and view the documentation of the code more intuitively.

Most of the time, we use this method to annotate classes, structs, enumerations, properties, methods

Multiline comment

/* First line comment second line comment third line comment */
Copy the code

In the code, if there are many consecutive single-line comments, you can replace them with multi-line comments to avoid writing many single-line comments, resulting in redundant code.

Multi-line documentation comments

/** Multi-line document comment */
Copy the code

You can add some MD syntax to a multi-line document comment to achieve a specific style for a document page.

Markup syntax in annotations

Writing Swift code program comments in Xcode itself has its own MarKDown syntax. There are also some special tags, which can be shown in the Mini code preview on the right, and can be viewed at the top file path level.

tag

// MARK: This is a sign
// MARK: - This is the sign with the dividing line
Copy the code

Used to mark code structures and can be seen in Xcode in the mini map on the right

// TODO:I'm going to write some code down here to do something.
// TODO:- There's an extra dividing line.
Copy the code

This is used to indicate the purpose or implementation logic of the code to be written next.

// FIXME:This place needs repairing.
Copy the code

Indicates that the code in this area needs to be fixed. There is some problem that needs to be fixed.

Documentation comments

⌘ + / in development we can use the ⌥ + ⌘ + / shortcut to generate documentation comments to the code.

-parameters: and -throws:, -returns: are special key character formats that are displayed on the document comment page.

/// Add two integers
/// - Parameters:
/// -a: the integer to the left of the plus sign
/// -b: integer to the right of the plus sign
/// -throws: Throws an error. This method does not throw an error, but only demonstrates additional annotation usage.
/ / / Returns: and
///
/// this is the sum of two integers.
func add(a: Int.b: Int) throws -> Int {
    return a + b
}
Copy the code

You can see the resulting document style in the figure below. Those keywords act as headings to make the document clearer. And Xcode automatically generates documentation based on the comment syntax.

In addition, MarkDown syntax can be used for writing in multi-line document comments. There are other keywords that can also be used in comment documents. See the code below, or learn MarkDown syntax yourself.

    /** add two integers # add (title 1) This method adds integers. Let num = func add(a: 1, b: 2) // print 3 (b: 2) '-c: Parameter 1 -d: Parameter 2 -f: parameter 3 -parameters: -a: an integer to the left of a plus sign. -b: an integer to the right of a plus sign. -Throws an error. - Returns: and -important: Pay attention to the parameters of this method. -version: 1.0.0 - Authors: Wei You, Fang Wang - Copyright: -Date: 2020-12-28 - Since: 1949-10-01 - Attention: Note: Please pay attention to the type when you use it. - Remark: Rebrand the method. - Warning: indicates a Warning that contains no content. - Bug: marks Bug problems. -TODO:Points improved code - Experiment: Test points for new gameplay. -Precondition: using the method -postcondition: using the method -requires: Something to use the method. -invariant: Invariant */
    func add(a: Int.b: Int) throws -> Int {
        return a + b
    }

Copy the code