From e519a03a1f0fc36849a5b80192ae2815902ba82b Mon Sep 17 00:00:00 2001 From: Craig Tiller Date: Fri, 6 Jan 2017 12:41:21 -0800 Subject: [PATCH] Small improvements to generated documentation --- doc/cpp/perf_notes.md | 4 +-- include/grpc++/grpc++.h | 4 +++ .../grpc++/impl/codegen/completion_queue.h | 6 ++-- templates/tools/doxygen/Doxyfile.include | 22 +++++++++----- tools/doxygen/Doxyfile.c++ | 30 ++++++++++++++++++- tools/doxygen/Doxyfile.c++.internal | 30 ++++++++++++++++++- tools/doxygen/Doxyfile.core | 29 +++++++++++++++++- tools/doxygen/Doxyfile.core.internal | 29 +++++++++++++++++- 8 files changed, 139 insertions(+), 15 deletions(-) diff --git a/doc/cpp/perf_notes.md b/doc/cpp/perf_notes.md index 805ead363874d..c87557558dd0f 100644 --- a/doc/cpp/perf_notes.md +++ b/doc/cpp/perf_notes.md @@ -10,9 +10,9 @@ If message k+1 in a stream does not rely on responses from message k, it's possible to enable write batching by passing a WriteOptions argument to Write with the buffer_hint set: -```c++ +~~~{.cpp} stream_writer->Write(message, WriteOptions().set_buffer_hint()); -``` +~~~ The write will be buffered until one of the following is true: - the per-stream buffer is filled (controllable with the channel argument diff --git a/include/grpc++/grpc++.h b/include/grpc++/grpc++.h index 36d65d6ee1eb6..daecfea406966 100644 --- a/include/grpc++/grpc++.h +++ b/include/grpc++/grpc++.h @@ -44,6 +44,10 @@ /// peer, compression settings, authentication, etc. /// - grpc::Server, representing a gRPC server, created by grpc::ServerBuilder. /// +/// Streaming calls are handled with the streaming classes in +/// \ref sync_stream.h and +/// \ref async_stream.h. +/// /// Refer to the /// [examples](https://github.com/grpc/grpc/blob/master/examples/cpp) /// for code putting these pieces into play. diff --git a/include/grpc++/impl/codegen/completion_queue.h b/include/grpc++/impl/codegen/completion_queue.h index 944f2c3919863..03cecdc21c61e 100644 --- a/include/grpc++/impl/codegen/completion_queue.h +++ b/include/grpc++/impl/codegen/completion_queue.h @@ -94,8 +94,10 @@ class ServerContext; extern CoreCodegenInterface* g_core_codegen_interface; -/// A thin wrapper around \a grpc_completion_queue (see / \a -/// src/core/surface/completion_queue.h). +/// A thin wrapper around \ref grpc_completion_queue (see \ref +/// src/core/lib/surface/completion_queue.h). +/// See \ref doc/cpp/perf_notes.md for notes on best practices for high +/// performance servers. class CompletionQueue : private GrpcLibraryCodegen { public: /// Default constructor. Implicitly creates a \a grpc_completion_queue diff --git a/templates/tools/doxygen/Doxyfile.include b/templates/tools/doxygen/Doxyfile.include index 8b0c528c1f68f..7fe8a297464e1 100644 --- a/templates/tools/doxygen/Doxyfile.include +++ b/templates/tools/doxygen/Doxyfile.include @@ -8,7 +8,9 @@ <%def name="gen_doxyfile(libnames, packagename, collection, internal)"> <% import itertools + import glob targets = [] + docpackage = packagename.replace('+', 'p').lower() for libname in libnames: target = None for p in collection: @@ -778,13 +780,19 @@ WARN_LOGFILE = # spaces. # Note: If this tag is empty the current directory is searched. -INPUT = ${' \\\n'.join( - itertools.chain.from_iterable( - target.public_headers + - ([] - if not internal - else target.headers + target.src) - for target in targets))} +INPUT = ${ + ' \\\n'.join( + itertools.chain( + itertools.chain.from_iterable( + target.public_headers + + ([] + if not internal + else target.headers + target.src) + for target in targets), + glob.glob('doc/*.md'), + glob.glob('doc/%s/*.md' % docpackage)) + ) +} # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/tools/doxygen/Doxyfile.c++ b/tools/doxygen/Doxyfile.c++ index 0f3ebde666a73..2c16f6f24a024 100644 --- a/tools/doxygen/Doxyfile.c++ +++ b/tools/doxygen/Doxyfile.c++ @@ -847,7 +847,35 @@ include/grpc/impl/codegen/slice.h \ include/grpc/impl/codegen/sync.h \ include/grpc/impl/codegen/sync_generic.h \ include/grpc/impl/codegen/sync_posix.h \ -include/grpc/impl/codegen/sync_windows.h +include/grpc/impl/codegen/sync_windows.h \ +doc/fail_fast.md \ +doc/compression.md \ +doc/environment_variables.md \ +doc/stress_test_framework.md \ +doc/PROTOCOL-WEB.md \ +doc/cpp-style-guide.md \ +doc/http-grpc-status-mapping.md \ +doc/wait-for-ready.md \ +doc/command_line_tool.md \ +doc/c-style-guide.md \ +doc/server_reflection_tutorial.md \ +doc/health-checking.md \ +doc/connection-backoff-interop-test-description.md \ +doc/epoll-polling-engine.md \ +doc/naming.md \ +doc/binary-logging.md \ +doc/connectivity-semantics-and-api.md \ +doc/connection-backoff.md \ +doc/compression_cookbook.md \ +doc/PROTOCOL-HTTP2.md \ +doc/load-balancing.md \ +doc/negative-http2-interop-test-descriptions.md \ +doc/server-reflection.md \ +doc/interop-test-descriptions.md \ +doc/statuscodes.md \ +doc/g_stands_for.md \ +doc/cpp/perf_notes.md \ +doc/cpp/pending_api_cleanups.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/tools/doxygen/Doxyfile.c++.internal b/tools/doxygen/Doxyfile.c++.internal index 73a4a090e19c3..e7fa25f1f1f9b 100644 --- a/tools/doxygen/Doxyfile.c++.internal +++ b/tools/doxygen/Doxyfile.c++.internal @@ -893,7 +893,35 @@ src/cpp/util/slice_cc.cc \ src/cpp/util/status.cc \ src/cpp/util/string_ref.cc \ src/cpp/util/time_cc.cc \ -src/cpp/codegen/codegen_init.cc +src/cpp/codegen/codegen_init.cc \ +doc/fail_fast.md \ +doc/compression.md \ +doc/environment_variables.md \ +doc/stress_test_framework.md \ +doc/PROTOCOL-WEB.md \ +doc/cpp-style-guide.md \ +doc/http-grpc-status-mapping.md \ +doc/wait-for-ready.md \ +doc/command_line_tool.md \ +doc/c-style-guide.md \ +doc/server_reflection_tutorial.md \ +doc/health-checking.md \ +doc/connection-backoff-interop-test-description.md \ +doc/epoll-polling-engine.md \ +doc/naming.md \ +doc/binary-logging.md \ +doc/connectivity-semantics-and-api.md \ +doc/connection-backoff.md \ +doc/compression_cookbook.md \ +doc/PROTOCOL-HTTP2.md \ +doc/load-balancing.md \ +doc/negative-http2-interop-test-descriptions.md \ +doc/server-reflection.md \ +doc/interop-test-descriptions.md \ +doc/statuscodes.md \ +doc/g_stands_for.md \ +doc/cpp/perf_notes.md \ +doc/cpp/pending_api_cleanups.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/tools/doxygen/Doxyfile.core b/tools/doxygen/Doxyfile.core index 6b6034a93488c..e7fc1dbc5739b 100644 --- a/tools/doxygen/Doxyfile.core +++ b/tools/doxygen/Doxyfile.core @@ -825,7 +825,34 @@ include/grpc/impl/codegen/slice.h \ include/grpc/impl/codegen/sync.h \ include/grpc/impl/codegen/sync_generic.h \ include/grpc/impl/codegen/sync_posix.h \ -include/grpc/impl/codegen/sync_windows.h +include/grpc/impl/codegen/sync_windows.h \ +doc/fail_fast.md \ +doc/compression.md \ +doc/environment_variables.md \ +doc/stress_test_framework.md \ +doc/PROTOCOL-WEB.md \ +doc/cpp-style-guide.md \ +doc/http-grpc-status-mapping.md \ +doc/wait-for-ready.md \ +doc/command_line_tool.md \ +doc/c-style-guide.md \ +doc/server_reflection_tutorial.md \ +doc/health-checking.md \ +doc/connection-backoff-interop-test-description.md \ +doc/epoll-polling-engine.md \ +doc/naming.md \ +doc/binary-logging.md \ +doc/connectivity-semantics-and-api.md \ +doc/connection-backoff.md \ +doc/compression_cookbook.md \ +doc/PROTOCOL-HTTP2.md \ +doc/load-balancing.md \ +doc/negative-http2-interop-test-descriptions.md \ +doc/server-reflection.md \ +doc/interop-test-descriptions.md \ +doc/statuscodes.md \ +doc/g_stands_for.md \ +doc/core/pending_api_cleanups.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/tools/doxygen/Doxyfile.core.internal b/tools/doxygen/Doxyfile.core.internal index 3f83911a01fdb..b13afdca99857 100644 --- a/tools/doxygen/Doxyfile.core.internal +++ b/tools/doxygen/Doxyfile.core.internal @@ -1276,7 +1276,34 @@ src/core/lib/support/tls_pthread.c \ src/core/lib/support/tmpfile_msys.c \ src/core/lib/support/tmpfile_posix.c \ src/core/lib/support/tmpfile_windows.c \ -src/core/lib/support/wrap_memcpy.c +src/core/lib/support/wrap_memcpy.c \ +doc/fail_fast.md \ +doc/compression.md \ +doc/environment_variables.md \ +doc/stress_test_framework.md \ +doc/PROTOCOL-WEB.md \ +doc/cpp-style-guide.md \ +doc/http-grpc-status-mapping.md \ +doc/wait-for-ready.md \ +doc/command_line_tool.md \ +doc/c-style-guide.md \ +doc/server_reflection_tutorial.md \ +doc/health-checking.md \ +doc/connection-backoff-interop-test-description.md \ +doc/epoll-polling-engine.md \ +doc/naming.md \ +doc/binary-logging.md \ +doc/connectivity-semantics-and-api.md \ +doc/connection-backoff.md \ +doc/compression_cookbook.md \ +doc/PROTOCOL-HTTP2.md \ +doc/load-balancing.md \ +doc/negative-http2-interop-test-descriptions.md \ +doc/server-reflection.md \ +doc/interop-test-descriptions.md \ +doc/statuscodes.md \ +doc/g_stands_for.md \ +doc/core/pending_api_cleanups.md # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses