How to dictate a Go doc comment without swallowing the sentence

Go doc comments must begin with the identifier being documented, which collides with VoiceGem's casing rule. Saying “pascal case parse config reads the file at path” returns ParseConfigReadsTheFileAtPath, because a casing run consumes every plain word until a symbol arrives.

A twelve-word Go doc comment takes about 14 seconds to type and about 4.4 seconds to say. (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

ParseConfigReadsTheConfigurationFileAtTheGivenPath

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

Step by step

1
Type the marker and the identifier
Write // and the exported name by hand. Both the slashes and the name resist dictation here, for two different reasons.
2
Dictate the rest of the sentence separately
Speak the description as its own utterance. Each VoiceGem dictation is an independent pass, so ending the utterance ends the casing run.
3
Or end the run with a symbol
Say a punctuation phrase after the identifier if one belongs there. A colon, comma or period stops the casing command consuming the sentence.
4
The manual route
Type the whole comment. Go's convention produces short doc comments and typing one is quick, which makes this the family where dictation adds least.

Go's doc-comment convention collides with the casing run in a way no other language does

The convention is that a doc comment starts with the name of the thing it documents, followed immediately by a verb: “ParseConfig reads the file at path.” No punctuation separates the identifier from the sentence, and a casing run ends only at a symbol, a whitespace command or another casing command.

Nothing in that sentence qualifies, so the Deterministic Pass consumes the whole thing into one PascalCase identifier. The workaround is to say the identifier and the sentence as two separate utterances, because each dictation is an independent pass over its own transcript.

Where the manual way breaks

Go doc comments are short by convention and typing one is fast. This is the language in this family where dictation adds the least, and the honest recommendation is to type the first few words.

Package comments are the exception. A package comment is a paragraph explaining what a package is for, it sits at the top of one file, and it is written once — which makes it the piece of Go documentation most likely to be too short because someone did not want to type it. Dictating that paragraph in VoiceGem is worth the two-utterance workaround.

Doing this somewhere else? a longer run through the speech-to-code converter, how dictating Javadoc comments works, the same thing for dictating JSDoc comments, or dictating Python docstrings, step by step.

Common questions

A VoiceGem casing run ends only at a symbol, a whitespace command or another casing command. Go's convention puts none of those between the name and the sentence.

Say the identifier and the sentence as two separate utterances. Each dictation is an independent pass, so ending one ends the casing run.

For short doc comments, usually not — type them. For a package comment that runs to a paragraph, yes.

Say the whole comment in one go and watch the sentence disappear.

Open the tool