Merge pull request #1738 from ctiller/explain-the-things

Initial Doxygen configuration

include/grpc/grpc.h

@@ -92,7 +92,8 @@ typedef struct {
   } value;
 } grpc_arg;
 
-/* An array of arguments that can be passed around.
+/** An array of arguments that can be passed around.
+    
     Used to set optional channel-level configuration.
     These configuration options are modelled as key-value pairs as defined
     by grpc_arg; keys are strings to allow easy backwards-compatible extension
@@ -192,15 +193,27 @@ typedef struct grpc_metadata {
   } internal_data;
 } grpc_metadata;
 
+/** The type of completion (for grpc_event) */
 typedef enum grpc_completion_type {
-  GRPC_QUEUE_SHUTDOWN, /* Shutting down */
-  GRPC_QUEUE_TIMEOUT,  /* No event before timeout */
-  GRPC_OP_COMPLETE     /* operation completion */
+  /** Shutting down */
+  GRPC_QUEUE_SHUTDOWN, 
+  /** No event before timeout */
+  GRPC_QUEUE_TIMEOUT,  
+  /** Operation completion */
+  GRPC_OP_COMPLETE     
 } grpc_completion_type;
 
+/** The result of an operation.
+
+    Returned by a completion queue when the operation started with tag. */
 typedef struct grpc_event {
+  /** The type of the completion. */
   grpc_completion_type type;
+  /** non-zero if the operation was successful, 0 upon failure. 
+      Only GRPC_OP_COMPLETE can succeed or fail. */
   int success;
+  /** The tag passed to grpc_call_start_batch etc to start this operation.
+      Only GRPC_OP_COMPLETE has a tag. */
   void *tag;
 } grpc_event;
 
@@ -322,34 +335,39 @@ typedef struct grpc_op {
   } data;
 } grpc_op;
 
-/* Initialize the grpc library.
+/** Initialize the grpc library.
+    
     It is not safe to call any other grpc functions before calling this.
     (To avoid overhead, little checking is done, and some things may work. We
     do not warrant that they will continue to do so in future revisions of this
     library). */
 void grpc_init(void);
 
-/* Shut down the grpc library.
+/** Shut down the grpc library.
+    
     No memory is used by grpc after this call returns, nor are any instructions
     executing within the grpc library.
     Prior to calling, all application owned grpc objects must have been
     destroyed. */
 void grpc_shutdown(void);
 
+/** Create a completion queue */
 grpc_completion_queue *grpc_completion_queue_create(void);
 
-/* Blocks until an event is available, the completion queue is being shut down,
-   or deadline is reached. Returns NULL on timeout, otherwise the event that
-   occurred.
+/** Blocks until an event is available, the completion queue is being shut down,
+    or deadline is reached. 
+
+    Returns NULL on timeout, otherwise the event that occurred.
 
     Callers must not call grpc_completion_queue_next and
     grpc_completion_queue_pluck simultaneously on the same completion queue. */
 grpc_event grpc_completion_queue_next(grpc_completion_queue *cq,
                                       gpr_timespec deadline);
 
-/* Blocks until an event with tag 'tag' is available, the completion queue is
-   being shutdown or deadline is reached. Returns NULL on timeout, or a pointer
-   to the event that occurred.
+/** Blocks until an event with tag 'tag' is available, the completion queue is
+    being shutdown or deadline is reached. 
+
+    Returns NULL on timeout, or a pointer to the event that occurred.
 
     Callers must not call grpc_completion_queue_next and
     grpc_completion_queue_pluck simultaneously on the same completion queue. */

templates/tools/doxygen/Doxyfile.c++.template

@@ -0,0 +1,2 @@
+<%namespace file="Doxyfile.include" import="gen_doxyfile"/>\
+${gen_doxyfile(['grpc++'], 'C++', libs)}

templates/tools/doxygen/Doxyfile.core.template

@@ -0,0 +1,2 @@
+<%namespace file="Doxyfile.include" import="gen_doxyfile"/>\
+${gen_doxyfile(['grpc', 'gpr'], 'Core', libs)}

tools/doxygen/run_doxygen.sh

@@ -0,0 +1,41 @@
+#!/bin/sh
+
+# Copyright 2015, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+set -ex
+
+# change to grpc repo root
+cd $(dirname $0)/../..
+
+for i in core c++
+do
+	mkdir -p doc/ref/$i
+	doxygen tools/doxygen/Doxyfile.$i
+done