Description

This PR improves the documentation for the KafkaProducer.send() method by clarifying what methods are available on the returned FutureRecordMetadata object.

Motivation

While practising the Kafka Python package by trying to build a consumer, I have tried to understand what was is that KafkaProducer.send() method was returning as an object.
Currently, the documentation, as per generated by Sphinx + autodoc did not display such information, states that send() returns a FutureRecordMetadata that "resolves to RecordMetadata", but it doesn't explain how to actually use this future object. Users need to dig through the source code to discover methods like get(), add_callback(), and add_errback().

Changes

• Enhanced the Returns section of KafkaProducer.send() docstring
• Added documentation for the main methods available on the returned future:
  • get(timeout=None): for synchronous/blocking behavior
  • add_callback(fn): for handling successful sends asynchronously
  • add_errback(fn): for handling failed sends asynchronously

Testing

• Verified the docstring renders correctly
• No code changes, only documentation improvements

Notes

I considered adding more detailed documentation directly on the FutureRecordMetadata class, but since it's not part of the public API (not exported in __init__.py), I kept the changes minimal and focused on the user-facing send() method.

Thank you for considering this contribution!