Addressing review feedback

src/core/channel/channel_stack_builder.c

@@ -39,9 +39,6 @@
 
 int grpc_trace_channel_stack_builder = 0;
 
-#define BEGIN_SENTINAL ((grpc_channel_filter *)1)
-#define END_SENTINAL ((grpc_channel_filter *)2)
-
 typedef struct filter_node {
   struct filter_node *next;
   struct filter_node *prev;
@@ -51,7 +48,7 @@ typedef struct filter_node {
 } filter_node;
 
 struct grpc_channel_stack_builder {
-  // sentinal nodes for filters that have been added
+  // sentinel nodes for filters that have been added
   filter_node begin;
   filter_node end;
   // various set/get-able parameters
@@ -69,8 +66,8 @@ grpc_channel_stack_builder *grpc_channel_stack_builder_create(void) {
   grpc_channel_stack_builder *b = gpr_malloc(sizeof(*b));
   memset(b, 0, sizeof(*b));
 
-  b->begin.filter = BEGIN_SENTINAL;
-  b->end.filter = END_SENTINAL;
+  b->begin.filter = NULL;
+  b->end.filter = NULL;
   b->begin.next = &b->end;
   b->begin.prev = &b->end;
   b->end.next = &b->begin;

src/core/channel/channel_stack_builder.h

@@ -39,100 +39,115 @@
 #include "src/core/channel/channel_args.h"
 #include "src/core/channel/channel_stack.h"
 
-// grpc_channel_stack_builder offers a programmatic interface to selected
-// and order channel filters
+/// grpc_channel_stack_builder offers a programmatic interface to selected
+/// and order channel filters
 typedef struct grpc_channel_stack_builder grpc_channel_stack_builder;
 typedef struct grpc_channel_stack_builder_iterator
     grpc_channel_stack_builder_iterator;
 
-// Create a new channel stack builder
+/// Create a new channel stack builder
 grpc_channel_stack_builder *grpc_channel_stack_builder_create(void);
 
-// Assign a name to the channel stack: string must be statically allocated
+/// Assign a name to the channel stack: \a name must be statically allocated
 void grpc_channel_stack_builder_set_name(grpc_channel_stack_builder *builder,
                                          const char *name);
 
-// Attach a transport to the builder (does not take ownership)
+/// Attach \a transport to the builder (does not take ownership)
 void grpc_channel_stack_builder_set_transport(
     grpc_channel_stack_builder *builder, grpc_transport *transport);
 
-// Fetch attached transport
+/// Fetch attached transport
 grpc_transport *grpc_channel_stack_builder_get_transport(
     grpc_channel_stack_builder *builder);
 
-// Set channel arguments: they must continue to exist until after
-// grpc_channel_stack_builder_finish returns
+/// Set channel arguments: \a args must continue to exist until after
+/// grpc_channel_stack_builder_finish returns
 void grpc_channel_stack_builder_set_channel_arguments(
     grpc_channel_stack_builder *builder, const grpc_channel_args *args);
 
-// Return a borrowed pointer to the channel arguments
+/// Return a borrowed pointer to the channel arguments
 const grpc_channel_args *grpc_channel_stack_builder_get_channel_arguments(
     grpc_channel_stack_builder *builder);
 
-// Begin iterating over already defined filters in the builder
+/// Begin iterating over already defined filters in the builder at the beginning
 grpc_channel_stack_builder_iterator *
 grpc_channel_stack_builder_create_iterator_at_first(
     grpc_channel_stack_builder *builder);
+
+/// Begin iterating over already defined filters in the builder at the end
 grpc_channel_stack_builder_iterator *
 grpc_channel_stack_builder_create_iterator_at_last(
     grpc_channel_stack_builder *builder);
 
-// Is an iterator at the first element?
+/// Is an iterator at the first element?
 bool grpc_channel_stack_builder_iterator_is_first(
     grpc_channel_stack_builder_iterator *iterator);
 
-// Is an iterator at the end?
+/// Is an iterator at the end?
 bool grpc_channel_stack_builder_iterator_is_end(
     grpc_channel_stack_builder_iterator *iterator);
 
-// Move an iterator to the next item
+/// Move an iterator to the next item
 bool grpc_channel_stack_builder_move_next(
     grpc_channel_stack_builder_iterator *iterator);
 
+/// Move an iterator to the previous item
 bool grpc_channel_stack_builder_move_prev(
     grpc_channel_stack_builder_iterator *iterator);
 
 typedef void (*grpc_post_filter_create_init_func)(
     grpc_channel_stack *channel_stack, grpc_channel_element *elem, void *arg);
 
-// Add a filter to the stack, after the given iterator
+/// Add \a filter to the stack, after \a iterator.
+/// Call \a post_init_func(..., \a user_data) once the channel stack is
+/// created.
 bool grpc_channel_stack_builder_add_filter_after(
     grpc_channel_stack_builder_iterator *iterator,
     const grpc_channel_filter *filter,
     grpc_post_filter_create_init_func post_init_func,
     void *user_data) GRPC_MUST_USE_RESULT;
 
-// Add a filter to the stack, before the given iterator
+/// Add \a filter to the stack, before \a iterator.
+/// Call \a post_init_func(..., \a user_data) once the channel stack is
+/// created.
 bool grpc_channel_stack_builder_add_filter_before(
     grpc_channel_stack_builder_iterator *iterator,
     const grpc_channel_filter *filter,
     grpc_post_filter_create_init_func post_init_func,
     void *user_data) GRPC_MUST_USE_RESULT;
 
-// Add a filter to the beginning of the filter list
+/// Add \a filter to the beginning of the filter list.
+/// Call \a post_init_func(..., \a user_data) once the channel stack is
+/// created.
 bool grpc_channel_stack_builder_prepend_filter(
     grpc_channel_stack_builder *builder, const grpc_channel_filter *filter,
     grpc_post_filter_create_init_func post_init_func,
     void *user_data) GRPC_MUST_USE_RESULT;
 
-// Add a filter to the end of the filter list
+/// Add \a filter to the end of the filter list.
+/// Call \a post_init_func(..., \a user_data) once the channel stack is
+/// created.
 bool grpc_channel_stack_builder_append_filter(
     grpc_channel_stack_builder *builder, const grpc_channel_filter *filter,
     grpc_post_filter_create_init_func post_init_func,
     void *user_data) GRPC_MUST_USE_RESULT;
 
-// Terminate iteration
+/// Terminate iteration and destroy \a iterator
 void grpc_channel_stack_builder_iterator_destroy(
     grpc_channel_stack_builder_iterator *iterator);
 
-// Destroy the builder, return the freshly minted channel stack
+/// Destroy the builder, return the freshly minted channel stack
+/// Allocates \a prefix_bytes bytes before the channel stack
+/// Returns the base pointer of the allocated block
+/// \a initial_refs, \a destroy, \a destroy_arg are as per
+/// grpc_channel_stack_init
 void *grpc_channel_stack_builder_finish(grpc_exec_ctx *exec_ctx,
                                         grpc_channel_stack_builder *builder,
                                         size_t prefix_bytes, int initial_refs,
                                         grpc_iomgr_cb_func destroy,
                                         void *destroy_arg);
 
-// Destroy the builder without creating a channel stack
+/// Destroy the builder without creating a channel stack
 void grpc_channel_stack_builder_destroy(grpc_channel_stack_builder *builder);
 
 extern int grpc_trace_channel_stack_builder;

src/core/surface/channel_init.h

@@ -31,8 +31,8 @@
  *
  */
 
-#ifndef GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_INIT_H
-#define GRPC_INTERNAL_CORE_CHANNEL_CHANNEL_INIT_H
+#ifndef GRPC_INTERNAL_CORE_SURFACE_CHANNEL_INIT_H
+#define GRPC_INTERNAL_CORE_SURFACE_CHANNEL_INIT_H
 
 #include "src/core/channel/channel_stack_builder.h"
 #include "src/core/surface/channel_stack_type.h"
@@ -43,8 +43,8 @@
 // It also provides a universal entry path to run those mutators to build
 // a channel stack for various subsystems.
 
-// One stage of mutation: call channel stack builder's to influence the finally
-// constructed channel stack
+// One stage of mutation: call functions against \a builder to influence the
+// finally constructed channel stack
 typedef bool (*grpc_channel_init_stage)(grpc_channel_stack_builder *builder,
                                         void *arg);
 
@@ -73,4 +73,4 @@ void *grpc_channel_init_create_stack(
     const grpc_channel_args *args, int initial_refs, grpc_iomgr_cb_func destroy,
     void *destroy_arg, grpc_transport *optional_transport);
 
-#endif
+#endif  // GRPC_INTERNAL_CORE_SURFACE_CHANNEL_INIT_H