Explain the newer semantics of grpc_error_add_child

src/core/lib/iomgr/error.cc

@@ -515,15 +515,20 @@ grpc_error* grpc_error_add_child(grpc_error* src, grpc_error* child) {
   GPR_TIMER_SCOPE("grpc_error_add_child", 0);
   if (src != GRPC_ERROR_NONE) {
     if (child == GRPC_ERROR_NONE) {
+      /* \a child is empty. Simply return the ref to \a src */
       return src;
     } else if (child != src) {
       grpc_error* new_err = copy_error_and_unref(src);
       internal_add_error(&new_err, child);
       return new_err;
     } else {
+      /* \a src and \a child are the same. Drop one of the references and return
+       * the other */
+      GRPC_ERROR_UNREF(child);
       return src;
     }
   } else {
+    /* \a src is empty. Simply return the ref to \a child */
     return child;
   }
 }

src/core/lib/iomgr/error.h

@@ -185,6 +185,13 @@ bool grpc_error_get_str(grpc_error* error, grpc_error_strs which,
 /// error occurring. Allows root causing high level errors from lower level
 /// errors that contributed to them. The src error takes ownership of the
 /// child error.
+///
+/// Edge Conditions -
+/// 1) If either of \a src or \a child is GRPC_ERROR_NONE, returns a reference
+/// to the other argument. 2) If both \a src and \a child are GRPC_ERROR_NONE,
+/// returns GRPC_ERROR_NONE. 3) If \a src and \a child point to the same error,
+/// returns a single reference. (Note that, 2 references should have been
+/// received to the error in this case.)
 grpc_error* grpc_error_add_child(grpc_error* src,
                                  grpc_error* child) GRPC_MUST_USE_RESULT;
 

test/core/iomgr/error_test.cc

@@ -187,16 +187,6 @@ static void test_os_error() {
   GRPC_ERROR_UNREF(error);
 }
 
-static void test_special() {
-  grpc_error* error = GRPC_ERROR_NONE;
-  error = grpc_error_add_child(
-      error, GRPC_ERROR_CREATE_FROM_STATIC_STRING("test child"));
-  intptr_t i;
-  GPR_ASSERT(grpc_error_get_int(error, GRPC_ERROR_INT_GRPC_STATUS, &i));
-  GPR_ASSERT(i == GRPC_STATUS_OK);
-  GRPC_ERROR_UNREF(error);
-}
-
 static void test_overflow() {
   grpc_error* error = GRPC_ERROR_CREATE_FROM_STATIC_STRING("Overflow");
 
@@ -235,7 +225,6 @@ int main(int argc, char** argv) {
   test_os_error();
   test_create_referencing();
   test_create_referencing_many();
-  test_special();
   test_overflow();
   grpc_shutdown();