Documenting code (DocC intro)
Write DocC comments (/// and /** ... */), document parameters/returns, add examples, and generate static docs for SwiftPM packages.
Documenting code (DocC intro) is a free Swift Academy lesson on CoddyKit — lesson 3 of 3. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, one of 3 lessons in the course, and your progress syncs across the web and the CoddyKit app.
Why DocC?
DocC turns well-placed comments into a browsable doc site.
- Use /// or /** ... */
- Describe what and show a tiny example
- Document parameters and returns
Function docs
Place /// directly above the declaration. Use lists for Parameters and Returns.
/// Adds two integers and returns the sum.
/// - Parameters:
/// - a: First addend.
/// - b: Second addend.
/// - Returns: The sum of `a` and `b`.
/// - Remark: Pure function; no side effects.
func sum(_ a: Int, _ b: Int) -> Int { a + b }
print(sum(2, 3)) // 5Type & member docs
Block comments /** ... */ work well for types; add short member docs with ///.
/** A simple counter that tracks a running total.
Use <code>increment()</code> to add one or a custom amount.
- Note: The type is value-based (a struct).
*/
struct Counter {
/// Current value of the counter.
private(set) var value: Int = 0
/// Increments the counter.
/// - Parameter amount: How much to add (default is 1).
mutating func increment(by amount: Int = 1) { value += amount }
}
var c = Counter()
c.increment()
c.increment(by: 3)
print("value =", c.value) // 4Examples section
Use a tiny Example section. Keep samples short for mobile screens.
/// Repeats a message a given number of times.
///
/// **Example**
/// ```swift
/// repeatMessage("Hi", times: 2) // prints twice
/// ```
/// - Parameters:
/// - text: Message to print.
/// - times: How many times to print.
func repeatMessage(_ text: String, times: Int) {
for _ in 0..<times { print(text) }
}
repeatMessage("Hi", times: 2)Build the docs
Use SwiftPM or Xcode to build docs. Prefer keeping docs inline so they stay up to date.
// Generate documentation for a SwiftPM package (examples):
// swift package generate-documentation --target MyLib
// swift package generate-documentation --target MyLib --output-path Docs
//
// Preview in Xcode (DocC):
// Product > Build Documentation
//
// Tip: keep docs close to code; DocC picks up symbols with /// or /** ... */.Doc style
Tips:
- Start with a one-line summary.
- Describe what it does, not internals.
- Document edge cases only if important.
- Prefer tiny examples over long prose.
DocC comment forms
Quick check: Which comments produce DocC docs?
Recap
Recap: Write DocC comments above symbols, include Parameters and Returns, add a tiny example, then generate docs via SwiftPM or Xcode.
Frequently asked questions
Is the “Documenting code (DocC intro)” lesson free?
Yes — the full text of “Documenting code (DocC intro)” is free to read here on the web, and the Swift Academy course includes 3 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Swift Academy course, upgrade to CoddyKit PRO.
What will I learn in “Documenting code (DocC intro)”?
Write DocC comments (/// and /** ... */), document parameters/returns, add examples, and generate static docs for SwiftPM packages. You practise Swift Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Swift Academy?
No prior experience is required. Swift Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 3 of 3, so you can start here or from the beginning and move at your own pace.
How long does the “Documenting code (DocC intro)” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Swift Academy lesson?
Yes. Every Swift Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- SwiftFormat / SwiftLint basics
- Style guide, API design guidelines
- Documenting code (DocC intro)