🔰DocC

🚧 施工中

Xcode ⟩ Documentation ⟩ DocC

what is DocC? 🚧

📗 參考

• Swift.org ⟩ Swift-DocC is Now Open Source

• WWDC21 ⟩ Create great documentation with DocC #todo ⭐️

• Hacking with Swift ⟩ How to document your project with DocC

• Use Your Loaf ⟩ Xcode DocC - Getting Started #todo ⭐️

• Ray ⟩ DocC Tutorial for Swift : Getting Started ⭐️

💈範例

/// DocC uses the first line of a comment as the summary.
///
/// Insert blank lines to break text into separate paragraphs.
///
/// You can use bulleted lists (use `-`, `+` or `*`):
///
/// - Text can be _emphasised_
/// - Or **strong**
///
/// Or numbered lists:
///
/// 7. The numbers you use make no difference
/// 0. The list will still be ordered, starting from 1
/// 5. But be sensible and just use 1, 2, 3 etc…
///
/// A [link][1] an an ![image][2]
///
/// # More Formats
///
/// ## Table
///
/// Sloth speed | Description
/// --- | ---
/// `slow` | Moves slightly faster than a snail.
/// `medium` | Moves at an average speed.
/// `fast` | Moves faster than a hare.
/// `supersonic` | Moves faster than the speed of sound.
///
///
/// ## Inline Code
///
/// - Use backticks for inline `code()`.
///
/// ## Code Block
///
/// - **Important**: when formatting your code listing, use spaces to indent lines instead of tabs.
/// - Also notice that code blocks scroll horizontally instead of wrapping.
///
/// ```swift
/// struct Sightseeing: Activity {
///   func perform(with sloth: inout Sloth) -> Speed {
///     sloth.energyLevel -= 10
///     return .slow
///   }
/// }
/// ```
///
/// ## Links & Images
///
/// Include [links](https://en.wikipedia.org/wiki/Hyperlink), and even images:
///
/// ![Swift Logo](/Users/Stuart/Downloads/swift.png "The logo for the Swift programming language")
///
/// A [link][1] an an ![image][2]
///
/// [1]: https://www.google.com
/// [2]: [e-mail]
///
/// - note: That "Note:" is written in bold.
/// - requires: A basic understanding of Markdown.
/// - seealso: `Error`, for a description of the errors that can be thrown.
struct Sloth {
    
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest
    /// habitats. They're especially happy to consume leaves and twigs, which they
    /// digest over long periods of time, mostly while they sleep.
    ///
    /// When they eat food, a sloth's ``energyLevel`` increases by the food's ``energy``.
    ///
    /// - Parameters:
    ///   - food: The food for the sloth to eat.
    ///   - quantity: The quantity of the food for the sloth to eat.
    ///
    /// - Returns: The sloth's energy level after eating.
    ///
    /// - Throws: `SlothError.tooMuchFood` if the quantity is more than 100.
    mutating public func eat(_ food: Food, quantity: Int) throws -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
    
    var energyLevel: Int = 0
}

struct Food {
    let name: String
    let energy: Int
}

struct MyProgram {
    func method() {
        var sloth = Sloth()
        let _ = try? sloth.eat(Food(name: "leaves", energy: 2), quantity: 100)
    }
}

📘 手冊

• DocC ⟩

  • Formatting Your Documentation Content - customized Markdown.

  • Adding Supplemental Content to a Documentation Catalog

• GitHub ⟩ Swift DocC

🗣 討論

• Does Swift have documentation generation support?