How to dictate Swift documentation comments in Xcode

Swift documentation comments open with a triple slash, and saying “slash slash slash” returns / / / with two spaces because the slash is division in VoiceGem's table. Type the marker; the Markdown body underneath is prose and dictates perfectly.

A thirteen-word documentation line is about 15 seconds of typing against about 4.8 seconds of speech. (sources: Dhakal, Feit, Kristensson & Oulasvirta, “Observations on Typing from 136 Million Keystrokes”, CHI 2018, 168,000 participants, 136 million keystrokes; Yuan, Liberman & Cieri, “Towards an Integrated Understanding of Speaking Rate in Conversation”, Interspeech 2006, 2,438 American English telephone conversations (Switchboard corpus). The speech figure is conversational rate, not a measured dictation rate — no such measurement exists.)

Say this

What lands in your editor

- Parameter userId: the identifier used to look up a cached profile

This tool runs entirely in your browser. Nothing you type is sent anywhere, stored, or logged.

Step by step

1
Type the triple-slash marker
Write /// by hand, or let Xcode insert a documentation block with its own shortcut. The slash keeps its spaces, so the marker cannot be dictated closed up.
2
Dictate the summary sentence
Say the description naturally. Swift documentation is Markdown prose, which is the shape the Deterministic Pass handles best because unrecognised words pass through untouched.
3
Say “dash” for a callout
Speak the phrase before Parameter or Returns. The hyphen arrives spaced, which is what a Markdown list item wants anyway.
4
Say “colon” after the callout name
Speak the phrase then the description. The colon attaches left, which matches Swift's documentation format exactly.

Swift documentation is Markdown, which is the best possible case for dictation

Xcode renders Swift documentation comments as Markdown in Quick Help, so the body is prose with light list formatting rather than a tag syntax. Prose is what the Deterministic Pass leaves alone, and the list markers Markdown uses are hyphens and colons that already want spaces.

Only the triple-slash marker resists. Every character in the body works, the callout syntax works, and the one thing that cannot be dictated is the three characters at the start of the line — which Xcode's own documentation shortcut inserts for you.

Where the manual way breaks

Xcode inserts a full documentation skeleton from a function signature with one keyboard shortcut, including a callout per parameter. Nothing spoken competes with that for structure.

Written prose is the gap. A skeleton with empty parameter descriptions renders as a Quick Help panel that says nothing, and filling it in is the part that gets skipped. Dictating the descriptions in VoiceGem makes writing them cost roughly what thinking them costs.

Doing this somewhere else? speech-to-code converter, on your own input, the same thing for dictating Go doc comments, dictating Javadoc comments, or dictating JSDoc comments, step by step.

Common questions

No. The slash keeps its spaces because its table entry serves division, so the marker arrives as three detached characters. Use Xcode's documentation shortcut.

Yes. The hyphen arrives spaced, which is what a Markdown list item wants, and the colon attaches left exactly as the format needs.

No. Documentation prose passes through VoiceGem untouched, apart from words that happen to be table phrases.

Dictate a parameter callout and check the hyphen and colon.

Open the tool