To take full advantage of the new documentation style, it’s important to know about Markdown statements, so skip this section if you already know. You can find a lot of information about Markdown online, for example there are some good readings here and here.

You can find other resources on Markdown statements. I’m only asking for the minimum basic statements here. Providing a full tutorial is not my concern, but focusing on the representation of the most commonly used Markdown statements.

You probably know (or maybe you just learned) that Markdown statements use special characters to format text, add resources (such as links or images), and mark special areas or text (such as ordered or unordered lists, blocks of code). These characters are easy to remember and can be deepened by repeated use or querying the list below. It’s interesting when you get used to Markdown statements that you can generate documents in different formats by using appropriate tables: HTML pages, PDF documents, and so on. Speaking of HTML, Markdown supports inline HTML, which means you can simply add HTML tags to text and render it appropriately. HTML is not the essence of Markdown, however, so focus on the statements in Markdown itself.

The following list contains commonly used Markdown statements:

• #text#: sets the text to header, as in HTML
  

  Equivalence. Two # characters are equal to each other

  The header until

  Similarly, the following # character is optional.

• **text**: Returns bold text with an asterisk.
• *text*: Returns the italic text in the middle of the asterisk.
• * text: Creates an unordered list item (registered with a space between the asterisk and the text), optionally using a “+” or “-” symbol.
• 1. Text: Create an ordered list item (list of numbers).
• [Linked text](some-url.com\): When the text is converted to a link.
• > text: creates a block reference
• A block of code written with 4 Spaces or TAB tags, as opposed to HTML

  Copy the codeCopy the code

  Label, which requires an additional 4 Spaces or 1 TAB character if you want to add abbreviations.

• If you don’t want to be confused with Spaces and tabs, you can write the code in ‘ ‘characters. For example, ‘var myProperty’ will display:var myProperty.
• Another way to create a code block is to add four (” “) symbols, then start writing the code, adding another four (” “) to the last line of the code.
• Use backslashes to disable rendering of special characters in Markdown statements. For example: /this/ will not appear in bold.

These are the most important elements to know about Markdown statements, and there are many more. This is enough to get you started, but if you want to learn more details, please check out more on your own.

Once you’re interested in Markdown, look for a free editor (online or Mac software) to give it a try. If you’re looking for an editor that supports live preview, you can watch your input translate directly to HTML and see the output immediately.

Editor’s note: Try the following editors: StackEdit (online), Typora, Macdown, Focused and Ulysses.

Documenting various entities in Swift requires following the rules of a few features. You can document attributes (variables and constants), methods, functions, classes, structs, structs, enumerations, protocols, extensions, and other code structures or entities. The document block needs to be written after the declaration or header of the entity, using 3 slashes or enclosing the code block in a structure like this:

/ * * * /Copy the code

The double slash (//) will be ignored by Xcode and will not render any document. Use double slashes in your code block (the body of a method) rather than when documenting the entire entity.

For a simple example of using a Markdown statement, document a simple attribute in the code below. I suggest you create a Playground in Xcode and play with the examples.

/// This is an **awesome** documentation line for a really *useful* variable.
var someVar = "This is a variable"Copy the code

The effect is as follows:

Note that “awesome” is shown in bold because it is covered by a double star, and “Useful” is covered by an asterisk and therefore in italics.

Let’s take another example, this time using a function:

/** It calculates and returns the outcome of the division of the two parameters. ## Important Notes ## 1. Both parameters are **double** numbers. 2. For a proper result the second parameter *must be other than 0*. 3. If the second parameter is 0 then the function will return nil. */ func performDivision(number1: Double, number2: Double) -> Double! { if number2 ! = 0 { return number1 / number2 } else { return nil } }Copy the code

Copy and paste the above code into the playground and hold down Option and click on the function name to see the quick help displayed:

There are two new Markdown elements, header and ordered list, in which list items are formatted in bold and italic. Note how easy it is to use Markdown’s special characters to enrich text styles in documents. The Quick Help Inspector shows the following:

Next, add a code block to the function’s documentation. In addition to creating blocks of code, the ‘ ‘symbol is often used to mark function names within lines

/**
    It doubles the value given as a parameter.

    ### Usage Example: ###
    ````
    let single = 5
    let double = doubleValue(single)
    print(double)
    ````

    * Use the `doubleValue(_:)` function to get the double value of any number.
    * Only ***Int*** properties are allowed.
*/
func doubleValue(value: Int) -> Int {
    return value * 2
}Copy the code

The effect is as follows:

Finally, let’s add some documentation to the enumeration and use it in the body of another function. The interesting thing here is that each element in the enumeration has a corresponding document:

/**
    My own alignment options.

    ````
    case Left
    case Center
    case Right
    ````
*/
enum AlignmentOptions {
    /// It aligns the text on the Left side.
    case Left

    /// It aligns the text on the Center.
    case Center

    /// It aligns the text on the Right side.
    case Right
}


func doSomething() {
    var alignmentOption: AlignmentOptions!

    alignmentOption = AlignmentOptions.Left
}Copy the code

Now Xcode displays the document for each element in the enumeration whenever it is used:

Note the dashes (-) before the keywords and the Spaces between them, followed by the actual arguments and their descriptions. As many parameters as exist here should be described (with appropriate descriptions).

Modify the above function slightly so that it returns fullname instead of just printing it. In this case, we need to add a new keyword that describes the return value of the function:

/**
    This is an extremely complicated method that concatenates the first and last name and produces the full name.

    - Parameter firstname: The first part of the full name.
    - Parameter lastname: The last part of the fullname.
    - Returns: The full name as a string value.
*/
func createFullName(firstname: String, lastname: String) -> String {
    return "\(firstname) \(lastname)"
}Copy the code

The effect is as follows:

The two keywords above (parameter and RETURNS) are the most commonly used. The fullname function splits the fullname into firstName and lastname in reverse:

/**
    Another complicated function.

    - Parameter fullname: The fullname that will be broken into its parts.
    - Returns: A *tuple* with the first and last name.

    - Remark:
        There's a counterpart function that concatenates the first and last name into a full name.

    - SeeAlso:  `createFullName(_:lastname:)`

*/
func breakFullName(fullname: String) -> (firstname: String, lastname: String) {
    let fullnameInPieces = fullname.componentsSeparatedByString(" ")
    return (fullnameInPieces[0], fullnameInPieces[1])
}Copy the code

There are two new elements: Remark and SeeAlso keywords. Using the first keyword you can highlight any important or special points to catch the reader’s attention. The SeeAlso keyword is often used to add associations to other parts of code (as in this case with a previous function), or to provide a link to a real URL. The following is displayed in quick Help:

Imagine that the above functions are just a part of what you share with other developers, and make it as good as you can. You want the people using this function to know two facts (or requirements) : The fullname argument cannot be nil. Fisrtname and lastName need to be included in fullName, separated by Spaces, for the function to work properly. You can update the document with the additional two keywords, Precondition and Requires, as shown below:

/**
    Another complicated function.

    - Parameter fullname: The fullname that will be broken into its parts.
    - Returns: A *tuple* with the first and last name.

    - Remark:
        There's a counterpart function that concatenates the first and last name into a full name.

    - SeeAlso:  `createFullName(_:lastname:)`

    - Precondition: `fullname` should not be nil.
    - Requires: Both first and last name should be parts of the full name, separated with a *space character*.

*/
func breakFullName(fullname: String) -> (firstname: String, lastname: String) {
    let fullnameInPieces = fullname.componentsSeparatedByString(" ")
    return (fullnameInPieces[0], fullnameInPieces[1])
}Copy the code

Looking to the future, you might want to make a note of the features you want to implement:

- Todo: Support middle name in the next version.Copy the code

You can also add warnings, versions, authors, and reminders:

/** Another complicated function. - Parameter fullname: The fullname that will be broken into its parts. - Returns: A *tuple* with the first and last name. - Remark: There's a counterpart function that concatenates the first and last name into a full name. - SeeAlso: `createFullName(_:lastname:)` - Precondition: `fullname` should not be nil. - Requires: Both first and last name should be parts of the full name, separated with a *space character*. - Todo: Support middle name in the next version. - Warning: A wonderful **crash** will be the result of A 'nil' argument. -version: 1.1 -author: Myself Only - Note: Too much documentation for such a small function. */ func breakFullName(fullname: String) -> (firstname: String, lastname: String) { let fullnameInPieces = fullname.componentsSeparatedByString(" ") return (fullnameInPieces[0], fullnameInPieces[1]) }Copy the code

This is what appears in quick Help:

The level of detail you understand above depends on your reception.Document important code as shown in the previous code snippet, and use basic elements for less important parts.

Apple provides a documentation of all the available keywords, and you can see a more detailed description here. Don’t miss it.

Assuming you’ve signed off the app, let’s see how Jazzy uses it. First use the CD command in terminal to enter the project folder:

cd path_to_project_folder
Copy the code

The simplest use is to simply type Jazzy and wait for it to complete, but these do not contain classes or other structures in the code that are not marked public. So if you want to include all structures, type the following command:

jazzy --min-acl internal
Copy the code

In addition, if your Swift is not the latest version you will not see Jazzy’s output, in which case you need to add a parameter to specify which swift version xcode supports:

Jazzy -- Swift-version 2.1.1 --min-acl internalCopy the code

It is highly recommended that you type Jazzy –help to see all the parameters available in Jazzy, and you may find many useful things to do to get the results you want.

Execute the generated document page, and the result is as follows:

The default output folder is named docs and saved in the root directory of the project (you can change it).

Use Finder to look at folders, open index.html in your browser, and you’ll see a default page style that looks a lot like an Apple document. Click on the link to see how the document looks. Now, try Jazzy in your project.