> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Swift Documentation Comment
Swift documentation comments are specialized annotations parsed by the Swift compiler and documentation generators (such as Xcode's Quick Help and Swift DocC) to produce rich, structured API reference material. They utilize a custom dialect of Markdown to format text, define symbol contracts, and establish cross-references.
## Syntax Variants
Swift supports two distinct delimiters for documentation comments:
**Single-line delimiters** use three forward slashes (`///`). This is the preferred convention in the Swift ecosystem for both single and multi-line documentation.
```swift theme={"dark"}
/// This is a single-line documentation comment.
```
**Block delimiters** use a slash followed by two asterisks (`/**`) to open, and an asterisk followed by a slash (`*/`) to close.
```swift theme={"dark"}
/**
This is a block documentation comment.
It spans multiple lines.
*/
```
## Structural Parsing
The Swift compiler implicitly divides documentation comments into three semantic sections based on line breaks:
1. **Summary:** The first paragraph. It is parsed as a concise, high-level description of the symbol.
2. **Discussion:** Any subsequent paragraphs separated from the summary by a blank line. This section supports standard Markdown elements like headings, lists, and code blocks.
3. **Callouts/Fields:** A structured list of keywords defining the symbol's inputs, outputs, and error states.
## Standard Callout Fields
Swift recognizes specific Markdown list items to populate dedicated UI fields in Quick Help and generated documentation.
* **`- Parameter [name]:`** Documents a single parameter.
* **`- Parameters:`** Documents multiple parameters using a nested list.
* **`- Returns:`** Documents the return value.
* **`- Throws:`** Documents the error types the function can throw.
```swift theme={"dark"}
/// Calculates the quotient of two integers.
///
/// This function performs standard integer division. If the denominator
/// is zero, the function will throw a `MathError`.
///
/// - Parameters:
/// - dividend: The number to be divided.
/// - divisor: The number by which to divide the dividend.
///
/// - Returns: The integer result of the division.
///
/// - Throws: `MathError.divisionByZero` if `divisor` is `0`.
func divide(_ dividend: Int, by divisor: Int) throws -> Int {
// ...
}
```
## Markdown Formatting and Symbol Linking
Documentation comments support standard Markdown formatting, including emphasis (`*italic*`, `**bold**`) and inline code (` `code` `).
Additionally, Swift DocC utilizes **Symbol Linking**. Enclosing a Swift symbol name in double backticks instructs the documentation compiler to resolve the symbol and generate an active hyperlink to that symbol's documentation page.
```swift theme={"dark"}
/// Initializes a new ``NetworkRequest`` instance.
///
/// Use this initializer before calling ``execute(with:)``.
```
## Custom Callouts
Beyond standard API fields, Swift supports arbitrary callouts using the `- [Keyword]:` syntax. The documentation compiler recognizes several standard keywords to render distinct visual styling (e.g., badges or colored blocks). Common recognized callouts include:
* `- Note:`
* `- Warning:`
* `- Important:`
* `- Experiment:`
```swift theme={"dark"}
/// - Warning: This method is not thread-safe.
/// - Note: For concurrent execution, use ``asyncExecute()``.
```
Tired of Poor Swift Skills? Fix That With Deep Grasping!
Learn More
