Merge github.com:grpc/grpc into oops-i-split-it-again

1 files changed, 40 insertions, 7 deletions

diff --git a/src/core/transport/stream_op.h b/src/core/transport/stream_op.h
index aae101edad..842fc932b9 100644
--- a/src/core/transport/stream_op.h
+++ b/src/core/transport/stream_op.h
@@ -85,29 +85,62 @@ typedef struct grpc_mdelem_list {
 } grpc_mdelem_list;
 
 typedef struct grpc_metadata_batch {
+  /** Metadata elements in this batch */
   grpc_mdelem_list list;
+  /** Elements that have been removed from the batch, but have
+      not yet been unreffed - used to allow collecting garbage
+      under a single metadata context lock */
   grpc_mdelem_list garbage;
+  /** Used to calculate grpc-timeout at the point of sending,
+      or gpr_inf_future if this batch does not need to send a
+      grpc-timeout */
   gpr_timespec deadline;
 } grpc_metadata_batch;
 
-void grpc_metadata_batch_init(grpc_metadata_batch *comd);
-void grpc_metadata_batch_destroy(grpc_metadata_batch *comd);
+void grpc_metadata_batch_init(grpc_metadata_batch *batch);
+void grpc_metadata_batch_destroy(grpc_metadata_batch *batch);
 void grpc_metadata_batch_merge(grpc_metadata_batch *target,
                                grpc_metadata_batch *add);
 
-void grpc_metadata_batch_link_head(grpc_metadata_batch *comd,
+/** Add \a storage to the beginning of \a batch. storage->md is
+    assumed to be valid. 
+    \a storage is owned by the caller and must survive for the
+    lifetime of batch. This usually means it should be around
+    for the lifetime of the call. */
+void grpc_metadata_batch_link_head(grpc_metadata_batch *batch,
                                    grpc_linked_mdelem *storage);
-void grpc_metadata_batch_link_tail(grpc_metadata_batch *comd,
+/** Add \a storage to the end of \a batch. storage->md is
+    assumed to be valid.
+    \a storage is owned by the caller and must survive for the
+    lifetime of batch. This usually means it should be around
+    for the lifetime of the call. */
+void grpc_metadata_batch_link_tail(grpc_metadata_batch *batch,
                                    grpc_linked_mdelem *storage);
 
-void grpc_metadata_batch_add_head(grpc_metadata_batch *comd,
+/** Add \a elem_to_add as the first element in \a batch, using
+    \a storage as backing storage for the linked list element.
+    \a storage is owned by the caller and must survive for the
+    lifetime of batch. This usually means it should be around
+    for the lifetime of the call.
+    Takes ownership of \a elem_to_add */
+void grpc_metadata_batch_add_head(grpc_metadata_batch *batch,
                                   grpc_linked_mdelem *storage,
                                   grpc_mdelem *elem_to_add);
-void grpc_metadata_batch_add_tail(grpc_metadata_batch *comd,
+/** Add \a elem_to_add as the last element in \a batch, using
+    \a storage as backing storage for the linked list element.
+    \a storage is owned by the caller and must survive for the
+    lifetime of batch. This usually means it should be around
+    for the lifetime of the call.
+    Takes ownership of \a elem_to_add */
+void grpc_metadata_batch_add_tail(grpc_metadata_batch *batch,
                                   grpc_linked_mdelem *storage,
                                   grpc_mdelem *elem_to_add);
 
-void grpc_metadata_batch_filter(grpc_metadata_batch *comd,
+/** For each element in \a batch, execute \a filter.
+    The return value from \a filter will be substituted for the
+    grpc_mdelem passed to \a filter. If \a filter returns NULL,
+    the element will be moved to the garbage list. */
+void grpc_metadata_batch_filter(grpc_metadata_batch *batch,
                                 grpc_mdelem *(*filter)(void *user_data,
                                                        grpc_mdelem *elem),
                                 void *user_data);