From 3b539b36de990e16d2ccee7636ed90eff60b484b Mon Sep 17 00:00:00 2001 From: Alexey Serbin Date: Tue, 16 Aug 2016 10:40:20 -0700 Subject: [PATCH] [docs] added Kudu version into the doxygen footer Added information on the Kudu source version into the HTML footer of the auto-generated doxygen docs of the Kudu C++ API. Removed sample.cc file from the list of files to process with doxygen. Change-Id: I3861aafa1e615cc991647704d9a4ce8d44ad678f Reviewed-on: http://gerrit.cloudera.org:8080/4165 Tested-by: Kudu Jenkins Reviewed-by: Adar Dembo --- CMakeLists.txt | 7 ++++++- docs/support/doxygen/client_api.doxy.in | 19 +++++++++++++++++++ docs/support/doxygen/client_api.footer.in | 9 +++++++++ src/kudu/client/shared_ptr.h | 13 ++++++++----- 4 files changed, 42 insertions(+), 6 deletions(-) create mode 100644 docs/support/doxygen/client_api.footer.in diff --git a/CMakeLists.txt b/CMakeLists.txt index 76ef662dad..9a652c02bf 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -982,9 +982,14 @@ if (UNIX) set(DOXY_SUBDIR ${CMAKE_CURRENT_BINARY_DIR}/docs/doxygen) set(DOXY_CLIENT_DESTDIR ${DOXY_SUBDIR}/tmp.client) set(DOXY_CLIENT_API_CFG ${DOXY_SUBDIR}/client_api.doxy) + set(DOXY_CLIENT_API_FOOTER ${DOXY_SUBDIR}/client_api.footer) set(DOXY_CLIENT_API_OUTDIR ${DOXY_SUBDIR}/client_api) - # NOTE: DOXY_CLIENT_API_OUTDIR is used in client_api.doxy.in template file + list(APPEND DOXY_CLIENT_API_EXCLUDE + "share/doc/kuduClient/samples/sample.cc") + # NOTE: DOXY_CLIENT_API_OUTDIR and DOXY_CLIENT_API_FOOTER are used + # in client_api.doxy.in template file configure_file(docs/support/doxygen/client_api.doxy.in ${DOXY_CLIENT_API_CFG} @ONLY) + configure_file(docs/support/doxygen/client_api.footer.in ${DOXY_CLIENT_API_FOOTER} @ONLY) add_custom_target(doxy_install_client_alt_destdir COMMAND ${CMAKE_COMMAND} -E remove_directory ${DOXY_CLIENT_DESTDIR} COMMAND DESTDIR=${DOXY_CLIENT_DESTDIR} ${CMAKE_MAKE_PROGRAM} install diff --git a/docs/support/doxygen/client_api.doxy.in b/docs/support/doxygen/client_api.doxy.in index b51a308108..b868df16d6 100644 --- a/docs/support/doxygen/client_api.doxy.in +++ b/docs/support/doxygen/client_api.doxy.in @@ -46,6 +46,25 @@ INPUT = # file to process, the recursive scan for files is turned on. RECURSIVE = YES +# The EXCLUDE tag can be used to specify files and/or directories that should be +# excluded from the INPUT source files. This way you can easily exclude a +# subdirectory from a directory tree whose root is specified with the INPUT tag. +# +# Note that relative paths are relative to the directory from which doxygen is +# run. +EXCLUDE = @DOXY_CLIENT_API_EXCLUDE@ + +# The HTML_FOOTER tag can be used to specify a user-defined HTML footer for each +# generated HTML page. If the tag is left blank doxygen will generate a standard +# footer. See HTML_HEADER for more information on how to generate a default +# footer and what special commands can be used inside the footer. See also +# section "Doxygen usage" for information on how to generate the default footer +# that doxygen normally uses. +# This tag requires that the tag GENERATE_HTML is set to YES. +# We add information about the Kudu version the documentation is generated for. +HTML_FOOTER = @DOXY_CLIENT_API_FOOTER@ + + # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path # into which the generated documentation will be written. If a relative path is # entered, it will be relative to the location where doxygen was started. If diff --git a/docs/support/doxygen/client_api.footer.in b/docs/support/doxygen/client_api.footer.in new file mode 100644 index 0000000000..536724c3da --- /dev/null +++ b/docs/support/doxygen/client_api.footer.in @@ -0,0 +1,9 @@ + +
+
+ Generated for Kudu version @KUDU_VERSION_NUMBER@ on $datetime by Doxygen $doxygenversion +
+ Copyright © $year The Apache Software Foundation. +
+ + diff --git a/src/kudu/client/shared_ptr.h b/src/kudu/client/shared_ptr.h index 731b8cb0ec..fb66a4bdc9 100644 --- a/src/kudu/client/shared_ptr.h +++ b/src/kudu/client/shared_ptr.h @@ -18,15 +18,18 @@ #ifndef KUDU_CLIENT_SHARED_PTR_H #define KUDU_CLIENT_SHARED_PTR_H +/// @file shared_ptr.h +/// @brief Smart pointer typedefs for externally-faced code. +/// /// Kudu uses c++11 features internally, but provides a client interface which /// does not require c++11. We use std::tr1::shared_ptr in our public interface /// to hold shared instances of KuduClient, KuduSession, and KuduTable. /// -/// Unfortunately, on OS X, libc++ is the default c++ standard library -/// implementation and is required when compiling with c++11, but it does not -/// include the tr1 APIs. As a workaround, we use std::shared_ptr on OS X, since -/// OS X is for development only, and it is acceptable to require clients to -/// compile with c++11. +/// Unfortunately, if using clang on OS X, libc++ is the default +/// C++ standard library implementation and it is required when compiling +/// with c++11. However, libc++ does not include the TR1 APIs. As a workaround, +/// we use std::shared_ptr on OS X. Since OS X is for development only, +/// it is acceptable to require clients to compile with c++11. /// /// In order to allow applications to compile against Kudu on both Linux and OS /// X, we provide this typedef which resolves to std::tr1::shared_ptr on Linux