Please see defect #246059, the 'lock' case in comment #1. The Lock hint is defined by a pattern and the fix is also driven by pattern (template). The bad thing is that {} in the search pattern is not associated with {} in the fix template, and so comments are not transferred, but (after additional bugs were fixed) migrated upwards the tree and will end up completely outside the compound statement.

The proposed API change allows to name certain trees in the search pattern. The matcher in java.source module then records TreePaths that correspond to the named pattern trees in the Occurrence structure.

The Hint infrastructure is then able to pass that information to hints, so individual hint implementations may use the named TreePaths for e.g. navigation inside the original source, so they can better pinpoint interesting places of the matching text.

Other usage, important for fixing #246059, is that JavaFixUtilities.rewriteFix, which works based on code templates can use the same named tree syntax to associate tree matches from Occurrence with trees of the newly generated code - this allows java.source generator to transfer comments and possibly whitespace more consistently.