How to dictate Rust doc comments and doctests

Rust doc comments do two different jobs and dictation suits them differently. Documentation prose passes through the Deterministic Pass untouched, while a doctest is real Rust living inside the comment and dictates exactly as the surrounding source does, spacing artifacts and all.

A fifteen-word doc comment costs roughly 17 seconds typed against roughly 5.5 seconds spoken. (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

###Panics
Panics when the delimiter is missing from the line

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

Step by step

1
Type the /// or //! marker
Write the marker by hand. Slashes keep their spaces, so a doc-comment marker cannot be dictated closed up in any of these languages.
2
Dictate the prose
Say the description naturally. Rust documentation is Markdown, and unrecognised words pass through VoiceGem untouched.
3
Say “hash hash hash” for a section heading
Speak the phrase three times for a Markdown heading. The hash binds rightward, so the three characters land against the heading text with one space to add.
4
Dictate doctest code as ordinary Rust
Speak the example the way you would speak the function. A doctest is compiled and run by cargo test, so it needs the same cleanup any dictated Rust needs.

A Rust doctest is real code, which changes what dictating a comment means

Most documentation is prose that nothing checks. Rust doc comments can contain examples that cargo test compiles and runs, which means the code inside the comment has to be correct — and dictating it produces the same reference and generic spacing artifacts as dictating the function itself.

The practical consequence is worth knowing before you start. Dictate the prose freely; treat the doctest as code, run rustfmt over the file, and let cargo test tell you whether the example still compiles. The Deterministic Pass makes no distinction between the two, because it never knows it is inside a comment.

Where doing it by hand breaks down

Rust IDEs insert doc-comment markers and cargo doc renders the result, so the structure is well tooled and typing the markers is trivial.

The explanatory paragraph is what tooling cannot supply. Rust's documentation culture expects a real explanation of when to use a function and what it panics on, and that paragraph is exactly the writing that gets shortened when it has to be typed. Dictating it in VoiceGem is the case this whole family is about.

Doing this somewhere else? a longer run through the speech-to-code converter, dictating Go doc comments specifically, dictating Javadoc comments specifically, or what changes for dictating JSDoc comments.

Common questions

Yes. Cargo test compiles and runs it, and VoiceGem never knows it is inside a comment, so reference and generic spacing artifacts appear exactly as they would in source.

No. Slashes keep their spaces, so the marker arrives detached. Type it or let your IDE insert it.

Say “hash hash hash”. The hash binds rightward, so the three characters land together against the heading text.

Dictate a doctest assertion and check it against the source version.

Open the tool