Swift DocumentationMattt & Nate Cook April Peng 🚩🌱

/**
    让我们随便来写点什么.

    @param 啦啦啦啦，这货是参数。

    @return 咯咯咯咯，这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }

/**
    让我们随便来写点什么.

    :param: 啦啦啦啦，这货是参数。

    :returns: 咯咯咯咯，这货是返回值。
*/
func foo(bar: String) -> AnyObject { ... }

/**
	你可以制作 *斜体*, **粗体**, 或 `代码` 的字体风格.

	- 列表很不错,
	- 但最好不要叠套
	- 子列表的格式

	  - 就不太好了.

	1. 有序列表也一样
	2. 对那些有序的东西来说;
	3. 阿拉伯数字
	4. 是唯一支持的格式.
*/

/**
	Definition list
		一些术语以及它们的定义.
	Format
		左对齐术语，放在缩进的定义下面.
		
	:Field header:
		字段列表隔开一些。
		
	:Another field: 字段列表可以紧跟开始，不需要另起一行并缩进。
		随后缩进的行也被视为内容的一部分.
*/

/**
	重复一个字符串 `times` 次.

	:param: str     需要重复的字符串.
	:param: times   需要重复 `str` 的次数.

	:returns: 一个重复了 `str` `times` 次的新字符串.
*/
func repeatString(str: String, times: Int) -> String {
	return join("", Array(count: times, repeatedValue: str))
}

/**
	`Shape` 实例的面积.

	计算取决于该实例的形状。如果是三角形，`area` 将相当于:

	  let height = triangle.calculateHeight()
	  let area = triangle.base * height / 2
*/
var area: CGFloat { get }

import Foundation

/// 🚲 一个两轮的，人力驱动的交通工具.
class Bicycle {
    /**
        车架样式.

        - Road: 用于街道或步道.
        - Touring: 用于长途.
        - Cruiser: 用于城镇周围的休闲之旅.
        - Hybrid: 用于通用运输.
    */
    enum Style {
        case Road, Touring, Cruiser, Hybrid
    }

    /**
        转换踏板功率为运动的机制。

        - Fixed: 一个单一的，固定的齿轮。
        - Freewheel: 一个可变速，脱开的齿轮。
    */
    enum Gearing {
        case Fixed
        case Freewheel(speeds: Int)
    }

    /**
        用于转向的硬件。

        - Riser: 一个休闲车把。
        - Café: 一个正常车把。
        - Drop: 一个经典车把.
        - Bullhorn: 一个超帅车把.
    */
    enum Handlebar {
        case Riser, Café, Drop, Bullhorn
    }

    /// 自行车的风格
    let style: Style

    /// 自行车的齿轮
    let gearing: Gearing

    /// 自行车的车把
    let handlebar: Handlebar

    /// 车架大小, 厘米为单位.
    let frameSize: Int

    /// 自行车行驶的旅程数
    private(set) var numberOfTrips: Int

    /// 自行车总共行驶的距离，米为单位
    private(set) var distanceTravelled: Double

    /**
        使用提供的部件及规格初始化一个新自行车。

        :param: style 自行车的风格
        :param: gearing 自行车的齿轮
        :param: handlebar 自行车的车把
        :param: centimeters 自行车的车架大小，单位为厘米

        :returns: 一个漂亮的，全新的，为你度身定做.
    */
    init(style: Style, gearing: Gearing, handlebar: Handlebar, frameSize centimeters: Int) {
        self.style = style
        self.gearing = gearing
        self.handlebar = handlebar
        self.frameSize = centimeters

        self.numberOfTrips = 0
        self.distanceTravelled = 0
    }

    /**
        把自行车骑出去遛一圈

        :param: meters 行驶的距离，单位为米
    */
    func travel(distance meters: Double) {
        if meters > 0 {
            distanceTravelled += meters
            ++numberOfTrips
        }
    }
}

// MARK: Printable

extension Bicycle: Printable {
    var description: String {
        var descriptors: [String] = []
        
        switch self.style {
        case .Road:
            descriptors.append("A road bike for streets or trails")
        case .Touring:
            descriptors.append("A touring bike for long journeys")
        case .Cruiser:
            descriptors.append("A cruiser bike for casual trips around town")
        case .Hybrid:
            descriptors.append("A hybrid bike for general-purpose transportation")
        }
        
        switch self.gearing {
        case .Fixed:
            descriptors.append("with a single, fixed gear")
        case .Freewheel(let n):
            descriptors.append("with a \(n)-speed freewheel gear")
        }
        
        switch self.handlebar {
        case .Riser:
            descriptors.append("and casual, riser handlebars")
        case .Café:
            descriptors.append("and upright, café handlebars")
        case .Drop:
            descriptors.append("and classic, drop handlebars")
        case .Bullhorn:
            descriptors.append("and powerful bullhorn handlebars")
        }
        
        descriptors.append("on a \(frameSize)\" frame")
        
        // FIXME: 使用格式化的距离
        descriptors.append("with a total of \(distanceTravelled) meters traveled over \(numberOfTrips) trips.")
        
        // TODO: 允许自行车被命名吗？
        
        return join(", ", descriptors)
    }
}

let bike = Bicycle(style: .Road, gearing: .Freewheel(speeds: 8), handlebar: .Drop, frameSize: 53)

bike.travel(distance: 1_500) // 到处晃一晃
bike.travel(distance: 200) // 骑车去市场

println(bike)
// “公路自行车，具有 8 速飞轮齿轮，经典，下降车把，53” 框架，总的行驶距离 2 次共 1700.0 米。“