add comments to pop/ack/changInvisibleTime, No Code change

[winglechen]

约1200行注释，无代码修改

[RockteMQ-AI]

Review by github-manager-bot

Summary

This PR adds approximately 1200 lines of Javadoc and inline comments across 30+ files in the Pop consumer, ACK, ChangeInvisibleTime, and related proxy/store code paths. No functional code changes.

Findings

• [Positive] PopLongPollingService.java — The class-level Javadoc clearly explains the core responsibilities (suspend/wake/timeout/retry-bridge/cleanup). This is very helpful for onboarding.

• [Positive] PopConsumerCache.java — Good documentation of the cache data structure (active vs removed trees) and the background scan lifecycle.

• [Warning] Multiple files — Several comments describe intended behavior rather than actual behavior. For example, inline comments like // offset is ok or // init context params and validate describe what the code should do but do not explain non-obvious logic. Comments should explain why, not just restate what the code does.

• [Warning] DefaultMessageStore.java — Comments added inside getMessage() method (e.g., // offset too small, // offset overflow one, // get message, roll to next file if needed) are essentially paraphrasing the existing status enum names. These add visual noise without improving comprehension.

• [Info] With 30+ files touched, this PR is large for a "comments only" change. Reviewers may have difficulty verifying comment accuracy at this scale. Consider splitting into smaller PRs by module (e.g., broker/pop first, then proxy, then store) to make reviews more focused.

Suggestions

1. Focus comments on why (design decisions, non-obvious constraints, edge cases) rather than what (restating the code).
2. Remove comments that simply paraphrase variable/method names (e.g., // init context vars before parameter initialization).
3. Consider breaking into 2-3 smaller PRs by module for easier review.

---

Automated review by github-manager-bot