How to dictate Javadoc descriptions and tags

Javadoc tags dictate cleanly because the at sign binds rightward, while the block markers do not because slashes and asterisks keep their spaces. Let IntelliJ generate the block from the signature, then dictate the descriptions that the generator leaves empty.

A thirteen-word parameter description 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

@param departmentIdTheDepartmentWhoseActiveUsersAreReturned

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

Step by step

1
Let the IDE generate the block
Type the block-comment trigger and let IntelliJ insert a tag per parameter. The markers cannot be dictated and the generator writes them correctly.
2
Dictate the summary
Say the first sentence naturally. Javadoc's first sentence becomes the summary line in generated documentation, so it is the one most worth writing well.
3
Say “at sign” for each tag
Speak the phrase then the tag name. The at sign is one of three right-attaching entries in VoiceGem's table, so @param and @return come out closed up.
4
Dictate the description after the parameter name
Say the explanation as ordinary English. Prose passes through untouched, which is the whole reason this page recommends dictating descriptions rather than structure.

Javadoc's generated skeleton and dictated prose divide the work cleanly

IntelliJ writes a Javadoc block from a method signature, complete with a tag for every parameter, the return and each checked exception. That structure is exactly what dictation is worst at, since the markers use slashes and asterisks and arrive spaced.

The descriptions are exactly what dictation is best at. Every one is a sentence of English, and unrecognised words pass through the Deterministic Pass untouched — so the division is not a compromise, it is each tool doing the half it is good at.

Where the manual way breaks

Nowhere, for the block structure. IntelliJ generates it faster and more correctly than any dictation workflow, and this page recommends using it.

Empty tags are the failure that matters. A generated Javadoc block with a @param line and no description after it is worse than no Javadoc, because it passes a lint check while documenting nothing. Dictating the descriptions in VoiceGem is what turns the generated skeleton into something a reader gains from.

Doing this somewhere else? the speech-to-code converter, how dictating Go doc comments works, what changes for dictating JSDoc comments, or how dictating Python docstrings works.

Common questions

No. Slashes and asterisks keep their spaces in VoiceGem's table, so let IntelliJ generate the block and dictate the text inside it.

Yes. The at sign binds rightward, so @param, @return and @throws all come out closed up against the tag name.

Say “open brace at sign link” then the type name. The braces arrive spaced and need closing, because the same characters open code blocks.

Dictate three parameter descriptions and see how little punctuation you said.

Open the tool