Emitting Diagnostics

Vend warnings and errors as part of an operation’s result.

Overview

When running a compilation from the command line docc prints all diagnostics as output. Emitting rich diagnostics is important for integrating the compilation output with automation tools or development environments.

The diagnostics emitted during discovery, loading, and processing documentation are available via the context problems.

Returning a diagnostic when a callback or a method expects it is straight-forward:

let explanation = "Level-1 headings are reserved for titles."
let diagnostic = Diagnostic(
    source: sourceURL, 
    severity: .warning, 
    range: heading.range, 
    identifier: "org.swift.docc.InvalidAdditionalTitle", 
    summary: "Invalid use of level-1 heading.", 
    explanation: explanation)

return Problem(diagnostic: diagnostic, possibleSolutions: [])

Topics

Diagnostics

struct Problem
A problem with a document along with possible solutions to the problem.
struct Diagnostic
A diagnostic explains a problem or issue that needs the end-user’s attention.
enum DiagnosticSeverity
The severity of a diagnostic.
struct DiagnosticNote
A diagnostic note is a simple string message that should appear somewhere in a document.
class DiagnosticEngine
A type that collects and dispatches diagnostics during compilation.
protocol DiagnosticConsumer
A type that can receive diagnostics.