Subcommand

examples

Synchronises the project’s compiled examples.

Declaration

workspace refresh examples

Discussion

When APIs change, it is easy to forget to update any examples in the documentation. Workspace allows examples to be synchronised with real, compiled source code in a test module. That way, when an API change makes an example invalid, it will be caught by the compiler.

Examples can be defined anywhere in the project, but usually the best place for them is in a test module.

To define an example, place it between ‘@example(identifier)’ and ‘@endExample’. Anything on the same line as either token will be ignored (such as ‘//’).

func forTheSakeOfLeavingTheGlobalScope() {
let a = 0
let b = 0
let c = 0

// @example(symmetry)
if a == b {
assert(b == a)
}
// @endExample

// @example(transitivity)
if a == b ∧ b == c {
assert(a == c)
}
// @endExample
}

To use an example in a symbol’s documentation, add one or more instances of ‘#example(0, identifier)’ to the line immediately preceding the documentation.

// #example(1, symmetry) #example(2, transitivity)
/// Returns `true` if `lhs` is equal to `rhs`.
///
/// Equality is symmetrical:
///
/// ```swift
/// (Workspace will automatically fill these in whenever the project is refreshed.)
/// ```
///
/// Equality is transitive:
///
/// ```swift
///
/// ```
func == (lhs: Thing, rhs: Thing) -> Bool {
return lhs.rawValue == rhs.rawValue
}

Subcommands

help

Displays usage information.

Options

•language [language preference]

A language to use instead of the one specified in preferences.

•no‐colour

Removes colour from the output.

•project [path]

The location of the target project if it is not at the current working directory.

•use‐version [version]

Attempts to download and temporarily use the specified version insead of the one which is installed.

Argument Types

[language preference]

A list of IETF language tags or language icons. Semicolons indicate fallback order. Commas indicate that multiple languages should be used. Examples: ‘en-GB’ or ‘🇬🇧EN’ → British English, ‘cy,en;fr’ → both Welsh and English, otherwise French

[path]

A file system path. The form ‘/...’ indicates an absolute path. The form ‘~/...’ indicates a path relative to the home directory. Anything else is interpreted relative to the current working directory.

[version]

A version number or ‘development’.

Linux macOS