Xcode MarkDown的代码文档 ( for swift )

移动组周技术分享

markdown在swift中的应用

goals

  • 描述各个属性、函数和类的真正用途
  • 高亮函数的输入和输出（参数和返回值）
  • 几个月后还能清晰地记得每个函数属性是为了什么
  • 使用工具制作具有专业外观的使用手册（比如：使用 Jazzy）
  • Xcode 里写的代码文档能被预览

markdown grammar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
#text#：文本标题
**text**：使文本具有加粗的效果
*text*：使文本具有斜体的效果
* text：使文本成为一个无序列表的元素，值得注意的是，有个 * 后面需要有一个空格。同样，可以使用 + 或 - 实现这个的功能
1.text：使文本成为一个有序列表的元素
[linked text](http://some-url.com)：使文本成为可以点击的超链接
![image show](http://www.appcoda.com/wp-content/uploads/2016/05/t52_3_help_inspector1.png)：可以显示图片
> text：创建一个块引用。
使用 4 个空格或 1 个 tab 来缩进所写的代码块，等价于 HTML 中的 \\ 标签。可以继续使用 4 个空格或 1 个 tab 来添加另一个缩进
如果不想使用空格或 tab 的话，可以使用 ` 。比如， `var myProperty` 会显示成 var myProperty
另一种创建代码块的方法是添加 4 个 `，并从下一行开始写具体的代码，最后添加 4 个 ` 表示结束
反斜杠修饰 Markdown 的特殊字符就可以避免 Markdown 语法的解析了。比如， \**this\** 就不会产生加粗的效果

注释区域： 3 个斜线（///）或以下面的形式开头：

1
2
3
/**
*/
Case
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
    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
    }
}

case image

quick look

关键词

  • Parameter
  • Returns
  • Remark
  • SeeAlso
  • Precondiction
  • Requires
  • Todo
  • Version
  • Author
  • Note
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
/**
    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]）
}

全关键字

Jazzy 自动产生代码文档

Jazzy 是一款可以为 Swift 和 Objective-C 代码产生具有 Apple 风格的代码文档工具。

效果如下

jazzy 效果

下面以Alamofire为例子：

jazzy –help 查看帮助

  • cd Alamofire 的项目path
  • jazzy –output /Users/xcodeyang/Desktop/jazzy_document

参考博客地址