How to dictate a JSDoc block, and which part to type
JSDoc block markers do not dictate: saying “slash star star” returns / * * with two spaces, because both characters are arithmetic operators in VoiceGem's table. Type the marker, then dictate the description and the tags, which is where the words actually are.
A twelve-word parameter description costs about 14 seconds typed against about 4.4 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.)
@param { string } userIdTheIdentifierToLookUpThis tool runs entirely in your browser. Nothing you type is sent anywhere, stored, or logged.
Step by step
- 1
Type the block marker
Write the opening and closing markers by hand. Both slashes and asterisks keep their spaces, so dictating a JSDoc block delimiter produces three detached characters.
- 2
Dictate the description
Say the summary sentence naturally. Prose is the easiest thing in the file to dictate, because unrecognised words pass through the Deterministic Pass untouched.
- 3
Say “at sign” for each tag
Speak the phrase then the tag name. The at sign binds rightward, so @param and @returns both come out closed up.
- 4
Expect braces around types to be spaced
Close the gaps in the type annotation afterwards. The brace entry keeps its spaces because the same characters open code blocks.
JSDoc tags dictate correctly and JSDoc markers do not
The split falls on one character group. Tag names use the at sign, which is one of only three right-attaching entries in VoiceGem's table, so @param and @returns arrive closed up exactly as JSDoc needs them.
Block markers use slashes and asterisks, both of which are arithmetic operators with spaces on either side. There is no phrasing that closes them, which makes the practical workflow to type the two markers once — most editors insert both from a snippet anyway — and dictate everything between.
Where the manual path breaks
Editors generate JSDoc skeletons from a function signature, complete with a @param line per parameter. That is faster than anything spoken and it is the right tool for the structure.
Descriptions are what the generator leaves blank, and blank descriptions are the reason JSDoc blocks are so often useless. A generated skeleton with empty summaries documents nothing, and filling them in is typing. Dictating the sentences into a VoiceGem-driven editor is where the block stops being decoration.
Doing this somewhere else? the speech-to-code converter on this site, dictating Go doc comments, what changes for dictating Javadoc comments, or dictating Python docstrings.
Common questions
No. In VoiceGem's table slashes and asterisks both keep their spaces, so the marker arrives as three detached characters. Type it or use an editor snippet.
Yes. The at sign binds rightward, so @param and @returns come out closed up exactly as JSDoc needs.
The brace entry keeps its spaces because the same characters open code blocks. Close the gaps after dictating the tag.
Dictate a param tag and its description and see both halves.
Open the tool