From 14111e9da17340b069bfc7082b9449ab1f8a63fa Mon Sep 17 00:00:00 2001
From: David Garcia Quintas <dgq@google.com>
Date: Mon, 31 Aug 2015 14:17:46 -0700
Subject: [PATCH] Added grpc++.h with mainpage docs.
Minor fixes to previously existing docs.
---
BUILD | 2 +
Makefile | 2 +
build.json | 1 +
.../cpp/helloworld/greeter_async_client.cc | 2 +-
include/grpc++/channel.h | 12 ++--
include/grpc++/completion_queue.h | 6 +-
include/grpc++/grpc++.h | 64 +++++++++++++++++++
include/grpc/grpc.h | 8 +--
tools/doxygen/Doxyfile.c++ | 1 +
tools/doxygen/Doxyfile.c++.internal | 1 +
tools/run_tests/sources_and_headers.json | 4 ++
vsprojects/grpc++/grpc++.vcxproj | 1 +
vsprojects/grpc++/grpc++.vcxproj.filters | 3 +
.../grpc++_unsecure/grpc++_unsecure.vcxproj | 1 +
.../grpc++_unsecure.vcxproj.filters | 3 +
15 files changed, 96 insertions(+), 15 deletions(-)
create mode 100644 include/grpc++/grpc++.h
diff --git a/BUILD b/BUILD
index 72a496dce1..26cdc7f640 100644
--- a/BUILD
+++ b/BUILD
@@ -729,6 +729,7 @@ cc_library(
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
@@ -819,6 +820,7 @@ cc_library(
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
diff --git a/Makefile b/Makefile
index 1c2fca3154..7396818802 100644
--- a/Makefile
+++ b/Makefile
@@ -4593,6 +4593,7 @@ PUBLIC_HEADERS_CXX += \
include/grpc++/create_channel.h \
include/grpc++/generic/async_generic_service.h \
include/grpc++/generic/generic_stub.h \
+ include/grpc++/grpc++.h \
include/grpc++/impl/call.h \
include/grpc++/impl/client_unary_call.h \
include/grpc++/impl/grpc_library.h \
@@ -4838,6 +4839,7 @@ PUBLIC_HEADERS_CXX += \
include/grpc++/create_channel.h \
include/grpc++/generic/async_generic_service.h \
include/grpc++/generic/generic_stub.h \
+ include/grpc++/grpc++.h \
include/grpc++/impl/call.h \
include/grpc++/impl/client_unary_call.h \
include/grpc++/impl/grpc_library.h \
diff --git a/build.json b/build.json
index 1e00771ee3..8a51249cd0 100644
--- a/build.json
+++ b/build.json
@@ -38,6 +38,7 @@
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
diff --git a/examples/cpp/helloworld/greeter_async_client.cc b/examples/cpp/helloworld/greeter_async_client.cc
index 1d2dad052e..d464629ec5 100644
--- a/examples/cpp/helloworld/greeter_async_client.cc
+++ b/examples/cpp/helloworld/greeter_async_client.cc
@@ -75,7 +75,7 @@ class GreeterClient {
ClientContext context;
// The producer-consumer queue we use to communicate asynchronously with the
- // gRPC runtmie.
+ // gRPC runtime.
CompletionQueue cq;
// Storage for the status of the RPC upon completion.
diff --git a/include/grpc++/channel.h b/include/grpc++/channel.h
index 0ad3cc4252..60c816d58a 100644
--- a/include/grpc++/channel.h
+++ b/include/grpc++/channel.h
@@ -72,12 +72,12 @@ class Channel GRPC_FINAL : public GrpcLibrary,
public:
~Channel();
- /// Get the current channel state. If the channel is in IDLE and try_to_connect
- /// is set to true, try to connect.
+ /// Get the current channel state. If the channel is in IDLE and
+ /// \a try_to_connect is set to true, try to connect.
grpc_connectivity_state GetState(bool try_to_connect);
- /// Return the tag on cq when the channel state is changed or deadline expires.
- /// GetState needs to called to get the current state.
+ /// Return the \a tag on \a cq when the channel state is changed or \a
+ /// deadline expires. \a GetState needs to called to get the current state.
template <typename T>
void NotifyOnStateChange(grpc_connectivity_state last_observed, T deadline,
CompletionQueue* cq, void* tag) {
@@ -85,8 +85,8 @@ class Channel GRPC_FINAL : public GrpcLibrary,
NotifyOnStateChangeImpl(last_observed, deadline_tp.raw_time(), cq, tag);
}
- /// Blocking wait for channel state change or deadline expiration.
- /// GetState needs to called to get the current state.
+ /// Blocking wait for channel state change or \a deadline expiration.
+ /// \a GetState needs to called to get the current state.
template <typename T>
bool WaitForStateChange(grpc_connectivity_state last_observed, T deadline) {
TimePoint<T> deadline_tp(deadline);
diff --git a/include/grpc++/completion_queue.h b/include/grpc++/completion_queue.h
index d8c885dd9d..9c6ea7ce14 100644
--- a/include/grpc++/completion_queue.h
+++ b/include/grpc++/completion_queue.h
@@ -77,8 +77,8 @@ class Server;
class ServerBuilder;
class ServerContext;
-// This class is a thin wrapper around \a grpc_completion_queue (see
-// \a src/core/surface/completion_queue.h).
+/// A thin wrapper around \a grpc_completion_queue (see / \a
+/// src/core/surface/completion_queue.h).
class CompletionQueue : public GrpcLibrary {
public:
/// Default constructor. Implicitly creates a \a grpc_completion_queue
@@ -86,7 +86,7 @@ class CompletionQueue : public GrpcLibrary {
CompletionQueue();
/// Wrap \a take, taking ownership of the instance.
- ///
+ ///
/// \param take The completion queue instance to wrap. Ownership is taken.
explicit CompletionQueue(grpc_completion_queue* take);
diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h
new file mode 100644
index 0000000000..af87b9ea55
--- /dev/null
+++ b/include/grpc++/grpc++.h
@@ -0,0 +1,64 @@
+/*
+ *
+ * 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.
+ *
+ */
+
+/// \mainpage gRPC C++ API
+///
+/// The gRPC C++ API mainly consists of the following classes:
+/// - grpc::Channel, which represents the connection to an endpoint. See [the
+/// gRPC Concepts page](http://www.grpc.io/docs/guides/concepts.html) for more
+/// details. Channels are created by the factory function grpc::CreateChannel.
+/// - grpc::CompletionQueue, the producer-consumer queue used for all
+/// asynchronous communication with the gRPC runtime.
+/// - grpc::ClientContext and grpc::ServerContext, where optional configuration
+/// for an RPC can be set, such as setting custom metadata to be conveyed to the
+/// peer, compression settings, authentication, etc.
+/// - grpc::Server, representing a gRPC server, created by grpc::ServerBuilder.
+///
+/// Refer to the [examples](https://github.com/grpc/grpc/blob/master/examples/cpp)
+/// for code putting these pieces into play.
+
+#ifndef GRPCXX_GRPCXX_H
+#define GRPCXX_GRPCXX_H
+
+#include <grpc/grpc.h>
+
+#include <grpc++/channel.h>
+#include <grpc++/client_context.h>
+#include <grpc++/completion_queue.h>
+#include <grpc++/create_channel.h>
+#include <grpc++/server.h>
+#include <grpc++/server_builder.h>
+#include <grpc++/server_context.h>
+
+#endif // GRPCXX_GRPCXX_H
+
diff --git a/include/grpc/grpc.h b/include/grpc/grpc.h
index a75f356312..47f3df6605 100644
--- a/include/grpc/grpc.h
+++ b/include/grpc/grpc.h
@@ -47,11 +47,9 @@ extern "C" {
/*! \mainpage GRPC Core
*
- * \section intro_sec The GRPC Core library is a low-level library designed
- * to be wrapped by higher level libraries.
- *
- * The top-level API is provided in grpc.h.
- * Security related functionality lives in grpc_security.h.
+ * The GRPC Core library is a low-level library designed to be wrapped by higher
+ * level libraries. The top-level API is provided in grpc.h. Security related
+ * functionality lives in grpc_security.h.
*/
/** Completion Queues enable notification of the completion of asynchronous
diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++
index 96708c0622..f120f77c79 100644
--- a/tools/doxygen/Doxyfile.c++
+++ b/tools/doxygen/Doxyfile.c++
@@ -766,6 +766,7 @@ include/grpc++/completion_queue.h \
include/grpc++/create_channel.h \
include/grpc++/generic/async_generic_service.h \
include/grpc++/generic/generic_stub.h \
+include/grpc++/grpc++.h \
include/grpc++/impl/call.h \
include/grpc++/impl/client_unary_call.h \
include/grpc++/impl/grpc_library.h \
diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal
index 185d24720c..7eabe52ecb 100644
--- a/tools/doxygen/Doxyfile.c++.internal
+++ b/tools/doxygen/Doxyfile.c++.internal
@@ -766,6 +766,7 @@ include/grpc++/completion_queue.h \
include/grpc++/create_channel.h \
include/grpc++/generic/async_generic_service.h \
include/grpc++/generic/generic_stub.h \
+include/grpc++/grpc++.h \
include/grpc++/impl/call.h \
include/grpc++/impl/client_unary_call.h \
include/grpc++/impl/grpc_library.h \
diff --git a/tools/run_tests/sources_and_headers.json b/tools/run_tests/sources_and_headers.json
index 939261da65..cd95ce4e82 100644
--- a/tools/run_tests/sources_and_headers.json
+++ b/tools/run_tests/sources_and_headers.json
@@ -13094,6 +13094,7 @@
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
@@ -13146,6 +13147,7 @@
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
@@ -13276,6 +13278,7 @@
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
@@ -13325,6 +13328,7 @@
"include/grpc++/create_channel.h",
"include/grpc++/generic/async_generic_service.h",
"include/grpc++/generic/generic_stub.h",
+ "include/grpc++/grpc++.h",
"include/grpc++/impl/call.h",
"include/grpc++/impl/client_unary_call.h",
"include/grpc++/impl/grpc_library.h",
diff --git a/vsprojects/grpc++/grpc++.vcxproj b/vsprojects/grpc++/grpc++.vcxproj
index 5f8b7d8f4c..ac91f62d2a 100644
--- a/vsprojects/grpc++/grpc++.vcxproj
+++ b/vsprojects/grpc++/grpc++.vcxproj
@@ -219,6 +219,7 @@
<ClInclude Include="..\..\include\grpc++\create_channel.h" />
<ClInclude Include="..\..\include\grpc++\generic\async_generic_service.h" />
<ClInclude Include="..\..\include\grpc++\generic\generic_stub.h" />
+ <ClInclude Include="..\..\include\grpc++\grpc++.h" />
<ClInclude Include="..\..\include\grpc++\impl\call.h" />
<ClInclude Include="..\..\include\grpc++\impl\client_unary_call.h" />
<ClInclude Include="..\..\include\grpc++\impl\grpc_library.h" />
diff --git a/vsprojects/grpc++/grpc++.vcxproj.filters b/vsprojects/grpc++/grpc++.vcxproj.filters
index 38b5e14e0b..ff275999d7 100644
--- a/vsprojects/grpc++/grpc++.vcxproj.filters
+++ b/vsprojects/grpc++/grpc++.vcxproj.filters
@@ -117,6 +117,9 @@
<ClInclude Include="..\..\include\grpc++\generic\generic_stub.h">
<Filter>include\grpc++\generic</Filter>
</ClInclude>
+ <ClInclude Include="..\..\include\grpc++\grpc++.h">
+ <Filter>include\grpc++</Filter>
+ </ClInclude>
<ClInclude Include="..\..\include\grpc++\impl\call.h">
<Filter>include\grpc++\impl</Filter>
</ClInclude>
diff --git a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj
index 68154c67ec..9365a247d4 100644
--- a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj
+++ b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj
@@ -219,6 +219,7 @@
<ClInclude Include="..\..\include\grpc++\create_channel.h" />
<ClInclude Include="..\..\include\grpc++\generic\async_generic_service.h" />
<ClInclude Include="..\..\include\grpc++\generic\generic_stub.h" />
+ <ClInclude Include="..\..\include\grpc++\grpc++.h" />
<ClInclude Include="..\..\include\grpc++\impl\call.h" />
<ClInclude Include="..\..\include\grpc++\impl\client_unary_call.h" />
<ClInclude Include="..\..\include\grpc++\impl\grpc_library.h" />
diff --git a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters
index 52582d3aed..925ee9c81a 100644
--- a/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters
+++ b/vsprojects/grpc++_unsecure/grpc++_unsecure.vcxproj.filters
@@ -102,6 +102,9 @@
<ClInclude Include="..\..\include\grpc++\generic\generic_stub.h">
<Filter>include\grpc++\generic</Filter>
</ClInclude>
+ <ClInclude Include="..\..\include\grpc++\grpc++.h">
+ <Filter>include\grpc++</Filter>
+ </ClInclude>
<ClInclude Include="..\..\include\grpc++\impl\call.h">
<Filter>include\grpc++\impl</Filter>
</ClInclude>
--
GitLab