AVRO-4313: [java] Clarify javaAnnotation validation comments

[iemejia]

What is the purpose of the change

Follow-up to AVRO-4313 / #3892. That fix tightened the regex that validates a
schema's javaAnnotation before it is copied verbatim into generated Java
source. The surrounding comments (and the regression test comments) were hard
to follow, so this rewrites them in plainer language.

The comments now explain:

• why the check exists — the javaAnnotation property is emitted verbatim
  into generated source, so it must be validated first;
• what an unescaped quote in a string literal would allow — a single literal
  running past its closing quote and swallowing injected code;
• how the regression test distinguishes the safely-escaped copy of the
  payload inside the SCHEMA$ constant from a real verbatim emission.

This is a comment-only change; no behavior change.

Verifying this change

This change is a trivial rework / code cleanup without any test coverage.
The existing annotationCannotBreakOutViaStringLiteral and the rest of the
compiler module suite continue to pass.

Documentation

• Does this pull request introduce a new feature? (no)
• If yes, how is the feature documented? (not applicable)

[Copilot]

Pull request overview

This PR clarifies the security rationale and mechanics behind javaAnnotation validation in the Java SpecificCompiler, and improves the readability of the associated regression test commentary (AVRO-4313 follow-up). The changes are comment-only and do not alter behavior.

Changes:

• Rewrites the annotationCannotBreakOutViaStringLiteral test comments to more plainly explain the injection scenario and why the assertion checks for unescaped quotes in generated code.
• Adds a clearer, higher-level comment block in SpecificCompiler describing why javaAnnotation is validated and what the regex sub-patterns are intended to prevent.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
lang/java/compiler/src/test/java/org/apache/avro/compiler/specific/TestSpecificCompiler.java	Clarifies the regression test’s intent and how it distinguishes safe schema-string embedding from unsafe verbatim code emission.
lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java	Adds clearer documentation for the javaAnnotation validation grammar and the string-literal constraints that prevent code injection.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[RyanSkraba]

Thanks -- it's important for these complicated PRs!

[RyanSkraba]

Cherry-picked to branch-1.12.