Document error.h better

src/core/lib/iomgr/error.c

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright 2015, Google Inc.
+ * Copyright 2016, Google Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -89,14 +89,10 @@ static const gpr_avl_vtable avl_vtable_errs = {
 
 static const char *error_int_name(grpc_error_ints key) {
   switch (key) {
-    case GRPC_ERROR_INT_STATUS_CODE:
-      return "status_code";
     case GRPC_ERROR_INT_ERRNO:
       return "errno";
     case GRPC_ERROR_INT_FILE_LINE:
       return "file_line";
-    case GRPC_ERROR_INT_WARNING:
-      return "warning";
     case GRPC_ERROR_INT_STREAM_ID:
       return "stream_id";
     case GRPC_ERROR_INT_GRPC_STATUS:

src/core/lib/iomgr/error.h

@@ -1,6 +1,6 @@
 /*
  *
- * Copyright 2015, Google Inc.
+ * Copyright 2016, Google Inc.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -39,49 +39,82 @@
 
 #include <grpc/support/time.h>
 
-// Opaque representation of an error.
-// Errors are refcounted objects that represent the result of an operation.
-// Ownership laws:
-//  if a grpc_error is returned by a function, the caller owns a ref to that
-//    instance
-//  if a grpc_error is passed to a grpc_closure callback function (functions
-//    with the signature:
-//      void (*f)(grpc_exec_ctx *exec_ctx, void *arg, grpc_error *error))
-//    then those functions do not automatically own a ref to error
-//  if a grpc_error is passed to *ANY OTHER FUNCTION* then that function takes
-//    ownership of the error
+/// Opaque representation of an error.
+/// Errors are refcounted objects that represent the result of an operation.
+/// Ownership laws:
+///  if a grpc_error is returned by a function, the caller owns a ref to that
+///    instance
+///  if a grpc_error is passed to a grpc_closure callback function (functions
+///    with the signature:
+///      void (*f)(grpc_exec_ctx *exec_ctx, void *arg, grpc_error *error))
+///    then those functions do not automatically own a ref to error
+///  if a grpc_error is passed to *ANY OTHER FUNCTION* then that function takes
+///    ownership of the error
+/// Errors have:
+///  a set of ints, strings, and timestamps that describe the error
+///  always present are:
+///    GRPC_ERROR_STR_FILE, GRPC_ERROR_INT_FILE_LINE - source location the error
+///      was generated
+///    GRPC_ERROR_STR_DESCRIPTION - a human readable description of the error
+///    GRPC_ERROR_TIME_CREATED - a timestamp indicating when the error happened
+///  an error can also have children; these are other errors that are believed
+///    to have contributed to this one. By accumulating children, we can begin
+///    to root cause high level failures from low level failures, without having
+///    to derive execution paths from log lines
 typedef struct grpc_error grpc_error;
 
 typedef enum {
+  /// 'errno' from the operating system
   GRPC_ERROR_INT_ERRNO,
+  /// __LINE__ from the call site creating the error
   GRPC_ERROR_INT_FILE_LINE,
-  GRPC_ERROR_INT_STATUS_CODE,
-  GRPC_ERROR_INT_WARNING,
+  /// stream identifier: for errors that are associated with an individual
+  /// wire stream
   GRPC_ERROR_INT_STREAM_ID,
+  /// grpc status code representing this error
   GRPC_ERROR_INT_GRPC_STATUS,
+  /// offset into some binary blob (usually represented by
+  /// GRPC_ERROR_STR_RAW_BYTES) where the error occurred
   GRPC_ERROR_INT_OFFSET,
+  /// context sensitive index associated with the error
   GRPC_ERROR_INT_INDEX,
+  /// context sensitive size associated with the error
   GRPC_ERROR_INT_SIZE,
+  /// http2 error code associated with the error (see the HTTP2 RFC)
   GRPC_ERROR_INT_HTTP2_ERROR,
+  /// TSI status code associated with the error
   GRPC_ERROR_INT_TSI_CODE,
+  /// grpc_security_status associated with the error
   GRPC_ERROR_INT_SECURITY_STATUS,
+  /// WSAGetLastError() reported when this error occurred
   GRPC_ERROR_INT_WSA_ERROR,
+  /// File descriptor associated with this error
   GRPC_ERROR_INT_FD,
 } grpc_error_ints;
 
 typedef enum {
+  /// top-level textual description of this error
   GRPC_ERROR_STR_DESCRIPTION,
+  /// source file in which this error occurred
   GRPC_ERROR_STR_FILE,
+  /// operating system description of this error
   GRPC_ERROR_STR_OS_ERROR,
+  /// syscall that generated this error
   GRPC_ERROR_STR_SYSCALL,
+  /// peer that we were trying to communicate when this error occurred
   GRPC_ERROR_STR_TARGET_ADDRESS,
+  /// grpc status message associated with this error
   GRPC_ERROR_STR_GRPC_MESSAGE,
+  /// hex dump (or similar) with the data that generated this error
   GRPC_ERROR_STR_RAW_BYTES,
+  /// tsi error string associated with this error
   GRPC_ERROR_STR_TSI_ERROR,
+  /// filename that we were trying to read/write when this error occurred
   GRPC_ERROR_STR_FILENAME,
 } grpc_error_strs;
 
 typedef enum {
+  /// timestamp of error creation
   GRPC_ERROR_TIME_CREATED,
 } grpc_error_times;
 
@@ -92,8 +125,17 @@ typedef enum {
 const char *grpc_error_string(grpc_error *error);
 void grpc_error_free_string(const char *str);
 
+/// Create an error - but use GRPC_ERROR_CREATE instead
 grpc_error *grpc_error_create(const char *file, int line, const char *desc,
                               grpc_error **referencing, size_t num_referencing);
+/// Create an error (this is the preferred way of generating an error that is
+///   not due to a system call - for system calls, use GRPC_OS_ERROR or
+///   GRPC_WSA_ERROR as appropriate)
+/// \a referencing is an array of num_referencing elements indicating one or
+/// more errors that are believed to have contributed to this one
+/// err = grpc_error_create(x, y, z, r, nr) is equivalent to:
+///   err = grpc_error_create(x, y, z, NULL, 0);
+///   for (i=0; i<nr; i++) err = grpc_error_add_child(err, r[i]);
 #define GRPC_ERROR_CREATE(desc) \
   grpc_error_create(__FILE__, __LINE__, desc, NULL, 0)
 
@@ -125,13 +167,18 @@ grpc_error *grpc_error_set_time(grpc_error *src, grpc_error_times which,
                                 gpr_timespec value);
 grpc_error *grpc_error_set_str(grpc_error *src, grpc_error_strs which,
                                const char *value);
+/// Add a child error: an error that is believed to have contributed to this
+/// error occurring. Allows root causing high level errors from lower level
+/// errors that contributed to them.
 grpc_error *grpc_error_add_child(grpc_error *src, grpc_error *child);
 grpc_error *grpc_os_error(const char *file, int line, int err,
                           const char *call_name);
+/// create an error associated with errno!=0 (an 'operating system' error)
 #define GRPC_OS_ERROR(err, call_name) \
   grpc_os_error(__FILE__, __LINE__, err, call_name)
 grpc_error *grpc_wsa_error(const char *file, int line, int err,
                            const char *call_name);
+/// windows only: create an error associated with WSAGetLastError()!=0
 #define GRPC_WSA_ERROR(err, call_name) \
   grpc_wsa_error(__FILE__, __LINE__, err, call_name)