[KIP-932] - Update ShareConsumer Api docs

[Kaushik Raina (k-raina)]

Summary

• Update API docs for share consumer

[confluent-cla-assistant]

🎉 All Contributor License Agreements have been signed. Ready to merge.
_{Please push an empty commit if you would like to re-run the checks to verify CLA status for all contributors.}

[Copilot]

Pull request overview

Updates the ShareConsumer user-facing API documentation (C-embedded docstrings) to reflect KIP-932 behavior and clarify usage/semantics for subscription, polling, acknowledgements, shutdown, and thread-safety expectations.

Changes:

• Expanded method docstrings for subscribe(), poll(), acknowledge() / acknowledge_offset(), and close() with clearer behavioral details and error conditions.
• Added high-level ShareConsumer class documentation describing record lock/acknowledgement modes, polling requirements, and explicit thread-safety warnings.
• Removed the outdated internal TODO block in favor of user-facing documentation.

---

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

[sonarqube-confluent]

Quality Gate passed

Issues
0 New issues
1 Fixed issue
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube