[jph]

These examples could both be much better IMHO with a top comment block that describes the purpose of the functionality and shows good usage examples. Something like this below, and ideally using runnable doc comments to help keep the comment correctly explaining the code.

Replace symbol placeholders in the input string with translated values. Scan the string for symbol placeholders that use the format "$foo". The format uses a dollar sign, then optional ASCII letter, then optional word characters. Each recognized symbol is replaced with its corresponding value.

Symbols are only replaced if the symbol exists i.e. getSymbol(String) returns non-null, and the symbol has not already been replaced in this invocation.

Example:

  - input = "Hello $name, welcome to $city!"

  - output -> "Hello Alice, welcome to Boston!"

Return the string with symbol placeholders replaced.

[Signez]

I think the argument against this kind of top comments is that it makes easier to forget to update them if you change the code it refers to.

A single line comment is easy to parse, read and spot as having to be changed when you patch something.