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. This is lesson 3 of 3. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Swift Academy learning path, and your progress syncs across the web and the CoddyKit app. The Swift Academy course includes 3 lessons in total.
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.
Learn Swift with an AI tutor — free
Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.
- Courses
- 122
- Lessons
- 409
Frequently Asked Questions
Is the “Documenting code (DocC intro)” lesson free?
Yes — any 3 lessons of the Swift Academy learning path, including “Documenting code (DocC intro)”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Swift Academy course includes 3 lessons in total.
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, so you can start here or from the beginning and move at your own pace. This is lesson 3 of 3.
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)