Add context for what additional_metadata might be used for.

cpp/src/arrow/c/abi.h

@@ -321,7 +321,9 @@ struct ArrowAsyncProducer {
 
   // Any additional metadata tied to a specific stream of data. This must either be NULL
   // or a valid pointer to metadata which is encoded in the same way schema metadata
-  // would be. Non-null metadata must be valid for the lifetime of this object.
+  // would be. Non-null metadata must be valid for the lifetime of this object. As an
+  // example a producer could use this to provide the total number of rows and/or batches
+  // in the stream if known.
   const char* additional_metadata;
 
   // producer-specific opaque data.

docs/source/format/CDeviceDataInterface.rst

@@ -811,10 +811,12 @@ The structure has the following fields:
 
     *Mandatory.* The producer object that the consumer will use to request additional data or cancel.
 
-    This object *MUST* be populated before calling the :c:member:`ArrowAsyncDeviceStreamHandler.on_schema`
+    This object *MUST* be populated by the producer before calling the :c:member:`ArrowAsyncDeviceStreamHandler.on_schema`
     callback. The producer maintains ownership of this object and must clean it up *after* calling
     the release callback on the ``ArrowAsyncDeviceStreamHandler``.
 
+    The consumer *CANNOT* assume that this is valid until the ``on_schema`` callback is called.
+
 .. c:member:: void* ArrowAsyncDeviceStreamHandler.private_data
 
     *Optional.* An opaque pointer to consumer-provided private data.
@@ -913,6 +915,8 @@ This producer-provided and managed object has the following fields:
 
     *Optional.* An additional metadata string to provide any extra context to the consumer. This *MUST*
     either be ``NULL`` or a valid string that is encoded in the same way as :c:member:`ArrowSchema.metadata`.
+    As an example, a producer could utilize this metadata to provide the total number of rows and/or batches
+    in the stream if known.
 
     If not ``NULL`` it *MUST* be valid for at least the lifetime of this object.