This is an automated email from the ASF dual-hosted git repository.
xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/incubator-opendal.git
The following commit(s) were added to refs/heads/main by this push:
new 61fbf0ca1 docs(bindings/cpp): use doxygen to generate API docs (#2988)
61fbf0ca1 is described below
commit 61fbf0ca18990d463426ac84c474b4fdb39e70ab
Author: Mingzhuo Yin <[email protected]>
AuthorDate: Fri Sep 1 10:53:33 2023 +0800
docs(bindings/cpp): use doxygen to generate API docs (#2988)
* docs(bindings/cpp): use doxygen to generate API docs
Signed-off-by: silver-ymz <[email protected]>
* update licenserc.toml
Signed-off-by: silver-ymz <[email protected]>
* move awesome-doxygen to build process
Signed-off-by: silver-ymz <[email protected]>
* update licenserc.toml
Signed-off-by: silver-ymz <[email protected]>
* use jedelivr cdn
Signed-off-by: silver-ymz <[email protected]>
---------
Signed-off-by: silver-ymz <[email protected]>
---
bindings/cpp/CMakeLists.txt | 23 +++-
bindings/cpp/CONTRIBUTING.md | 19 +++
bindings/cpp/Doxyfile | 243 +++++++++++++++++++++++++++++++++++++++
bindings/cpp/include/opendal.hpp | 30 +++++
4 files changed, 314 insertions(+), 1 deletion(-)
diff --git a/bindings/cpp/CMakeLists.txt b/bindings/cpp/CMakeLists.txt
index 429fbc18f..adf4a5b53 100644
--- a/bindings/cpp/CMakeLists.txt
+++ b/bindings/cpp/CMakeLists.txt
@@ -80,4 +80,25 @@ if(APPLE)
endif()
include(GoogleTest)
-gtest_discover_tests(opendal_cpp_test)
\ No newline at end of file
+gtest_discover_tests(opendal_cpp_test)
+
+# Documentation
+set(PROJECT_DOCUMENT_SOURCE ${CMAKE_SOURCE_DIR}/include
${CMAKE_SOURCE_DIR}/README.md)
+string(REPLACE ";" " " PROJECT_DOCUMENT_SOURCE "${PROJECT_DOCUMENT_SOURCE}")
+file(DOWNLOAD
https://cdn.jsdelivr.net/gh/jothepro/[email protected]/doxygen-awesome.min.css
${CMAKE_BINARY_DIR}/doxygen-awesome.css)
+find_package(Doxygen)
+if (DOXYGEN_FOUND)
+ set(DOXYGEN_IN ${CMAKE_SOURCE_DIR}/Doxyfile)
+ set(DOXYGEN_OUT ${CMAKE_BINARY_DIR}/Doxyfile.out)
+
+ configure_file(${DOXYGEN_IN} ${DOXYGEN_OUT} @ONLY)
+ message("Doxygen build started")
+
+ add_custom_target(docs
+ COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_OUT}
+ WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+ COMMENT "Generating API documentation with Doxygen"
+ VERBATIM )
+else (DOXYGEN_FOUND)
+ message("Doxygen need to be installed to generate the doxygen
documentation")
+endif (DOXYGEN_FOUND)
\ No newline at end of file
diff --git a/bindings/cpp/CONTRIBUTING.md b/bindings/cpp/CONTRIBUTING.md
index f6a934c94..a6238d7b5 100644
--- a/bindings/cpp/CONTRIBUTING.md
+++ b/bindings/cpp/CONTRIBUTING.md
@@ -6,6 +6,7 @@
- [Bring your own toolbox](#bring-your-own-toolbox)
- [Build](#build)
- [Test](#test)
+ - [Documentation](#documentation)
## Setup
@@ -31,6 +32,10 @@ To build OpenDAL C++ binding, the following is all you need:
- **GTest(Google Test)**. It is used to run the tests. To see how to build,
check [here](https://github.com/google/googletest).
+- **Doxygen**. It is used to generate the documentation. To see how to build,
check [here](https://www.doxygen.nl/manual/install.html).
+
+- **Graphviz**. It is used to generate the documentation with graphs. To see
how to build, check [here](https://graphviz.org/download/).
+
For Ubuntu and Debian:
```shell
@@ -51,6 +56,9 @@ sudo make
sudo cp lib/*.a /usr/lib
sudo ln -s /usr/lib/libgtest.a /usr/local/lib/libgtest.a
sudo ln -s /usr/lib/libgtest_main.a /usr/local/lib/libgtest_main.a
+
+# install Doxygen and Graphviz
+sudo apt install doxygen graphviz
```
For MacOS:
@@ -67,6 +75,9 @@ brew install clang-format
# install GTest library
brew install googletest
+
+# install Doxygen and Graphviz
+brew install doxygen graphviz
```
## Build
@@ -101,3 +112,11 @@ You should build the project first. Then run:
```shell
ninja test
```
+
+## Documentation
+
+To build the documentation. (Note that you need to install doxygen, graphviz)
+
+```shell
+ninja docs
+```
\ No newline at end of file
diff --git a/bindings/cpp/Doxyfile b/bindings/cpp/Doxyfile
new file mode 100644
index 000000000..29c815c02
--- /dev/null
+++ b/bindings/cpp/Doxyfile
@@ -0,0 +1,243 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+PROJECT_NAME = "OpenDAL Cpp Binding"
+PROJECT_BRIEF = "The Cpp binding for Apache OpenDAL"
+OUTPUT_DIRECTORY = @CMAKE_CURRENT_BINARY_DIR@/docs_doxygen/
+EXCLUDE_SYMBOLS = ""
+USE_MDFILE_AS_MAINPAGE = "README.md"
+
+DOXYFILE_ENCODING = UTF-8
+CREATE_SUBDIRS = NO
+CREATE_SUBDIRS_LEVEL = 8
+ALLOW_UNICODE_NAMES = NO
+OUTPUT_LANGUAGE = English
+BRIEF_MEMBER_DESC = YES
+REPEAT_BRIEF = YES
+ABBREVIATE_BRIEF = "The $name class" \
+ "The $name widget" \
+ "The $name file" \
+ is \
+ provides \
+ specifies \
+ contains \
+ represents \
+ a \
+ an \
+ the
+ALWAYS_DETAILED_SEC = NO
+INLINE_INHERITED_MEMB = NO
+FULL_PATH_NAMES = YES
+SHORT_NAMES = NO
+JAVADOC_AUTOBRIEF = NO
+JAVADOC_BANNER = NO
+QT_AUTOBRIEF = NO
+MULTILINE_CPP_IS_BRIEF = NO
+PYTHON_DOCSTRING = YES
+INHERIT_DOCS = YES
+SEPARATE_MEMBER_PAGES = NO
+TAB_SIZE = 4
+OPTIMIZE_OUTPUT_FOR_C = NO
+OPTIMIZE_OUTPUT_JAVA = NO
+OPTIMIZE_FOR_FORTRAN = NO
+OPTIMIZE_OUTPUT_VHDL = NO
+OPTIMIZE_OUTPUT_SLICE = NO
+MARKDOWN_SUPPORT = YES
+TOC_INCLUDE_HEADINGS = 5
+AUTOLINK_SUPPORT = YES
+BUILTIN_STL_SUPPORT = NO
+CPP_CLI_SUPPORT = NO
+SIP_SUPPORT = NO
+IDL_PROPERTY_SUPPORT = YES
+DISTRIBUTE_GROUP_DOC = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS = NO
+TYPEDEF_HIDES_STRUCT = NO
+LOOKUP_CACHE_SIZE = 0
+NUM_PROC_THREADS = 1
+EXTRACT_ALL = ALL
+EXTRACT_PRIVATE = NO
+EXTRACT_PRIV_VIRTUAL = NO
+EXTRACT_PACKAGE = NO
+EXTRACT_STATIC = NO
+EXTRACT_LOCAL_CLASSES = YES
+EXTRACT_LOCAL_METHODS = NO
+EXTRACT_ANON_NSPACES = NO
+RESOLVE_UNNAMED_PARAMS = YES
+HIDE_UNDOC_MEMBERS = NO
+HIDE_UNDOC_CLASSES = NO
+HIDE_FRIEND_COMPOUNDS = NO
+HIDE_IN_BODY_DOCS = NO
+INTERNAL_DOCS = NO
+CASE_SENSE_NAMES = SYSTEM
+HIDE_SCOPE_NAMES = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_HEADERFILE = YES
+SHOW_INCLUDE_FILES = YES
+SHOW_GROUPED_MEMB_INC = NO
+FORCE_LOCAL_INCLUDES = NO
+INLINE_INFO = YES
+SORT_MEMBER_DOCS = YES
+SORT_BRIEF_DOCS = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES = NO
+SORT_BY_SCOPE_NAME = NO
+STRICT_PROTO_MATCHING = NO
+GENERATE_TODOLIST = YES
+GENERATE_TESTLIST = YES
+GENERATE_BUGLIST = YES
+GENERATE_DEPRECATEDLIST= YES
+MAX_INITIALIZER_LINES = 30
+SHOW_USED_FILES = YES
+SHOW_FILES = YES
+SHOW_NAMESPACES = YES
+QUIET = NO
+WARNINGS = YES
+WARN_IF_UNDOCUMENTED = YES
+WARN_IF_DOC_ERROR = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC = NO
+WARN_AS_ERROR = NO
+WARN_FORMAT = "$file:$line: $text"
+WARN_LINE_FORMAT = "at line $line of file $file"
+INPUT = @PROJECT_DOCUMENT_SOURCE@
+INPUT_ENCODING = UTF-8
+FILE_PATTERNS = *.hpp \
+ *.md
+RECURSIVE = YES
+EXCLUDE_SYMLINKS = NO
+EXAMPLE_PATTERNS = *
+EXAMPLE_RECURSIVE = NO
+FILTER_SOURCE_FILES = NO
+FORTRAN_COMMENT_AFTER = 72
+SOURCE_BROWSER = NO
+INLINE_SOURCES = NO
+STRIP_CODE_COMMENTS = YES
+REFERENCED_BY_RELATION = NO
+REFERENCES_RELATION = NO
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS = YES
+USE_HTAGS = NO
+VERBATIM_HEADERS = YES
+ALPHABETICAL_INDEX = YES
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+HTML_FILE_EXTENSION = .html
+HTML_COLORSTYLE = LIGHT
+HTML_COLORSTYLE_HUE = 220
+HTML_COLORSTYLE_SAT = 100
+HTML_COLORSTYLE_GAMMA = 80
+HTML_DYNAMIC_MENUS = YES
+HTML_DYNAMIC_SECTIONS = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET = NO
+DOCSET_FEEDNAME = "Doxygen generated docs"
+DOCSET_BUNDLE_ID = org.doxygen.Project
+DOCSET_PUBLISHER_ID = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME = Publisher
+GENERATE_HTMLHELP = NO
+GENERATE_CHI = NO
+BINARY_TOC = NO
+TOC_EXPAND = NO
+GENERATE_QHP = NO
+QHP_NAMESPACE = org.doxygen.Project
+QHP_VIRTUAL_FOLDER = doc
+GENERATE_ECLIPSEHELP = NO
+ECLIPSE_DOC_ID = org.doxygen.Project
+DISABLE_INDEX = NO
+GENERATE_TREEVIEW = NO
+FULL_SIDEBAR = NO
+ENUM_VALUES_PER_LINE = 4
+TREEVIEW_WIDTH = 250
+EXT_LINKS_IN_WINDOW = NO
+OBFUSCATE_EMAILS = YES
+HTML_FORMULA_FORMAT = png
+FORMULA_FONTSIZE = 10
+USE_MATHJAX = NO
+MATHJAX_VERSION = MathJax_2
+MATHJAX_FORMAT = HTML-CSS
+SEARCHENGINE = YES
+SERVER_BASED_SEARCH = NO
+EXTERNAL_SEARCH = NO
+SEARCHDATA_FILE = searchdata.xml
+GENERATE_LATEX = NO
+LATEX_OUTPUT = latex
+MAKEINDEX_CMD_NAME = makeindex
+LATEX_MAKEINDEX_CMD = makeindex
+COMPACT_LATEX = NO
+PAPER_TYPE = a4
+PDF_HYPERLINKS = YES
+USE_PDFLATEX = YES
+LATEX_BATCHMODE = NO
+LATEX_HIDE_INDICES = NO
+LATEX_BIB_STYLE = plain
+RTF_OUTPUT = rtf
+COMPACT_RTF = NO
+RTF_HYPERLINKS = NO
+GENERATE_MAN = NO
+MAN_OUTPUT = man
+MAN_EXTENSION = .3
+MAN_LINKS = NO
+GENERATE_XML = NO
+XML_OUTPUT = xml
+XML_PROGRAMLISTING = YES
+XML_NS_MEMB_FILE_SCOPE = NO
+GENERATE_DOCBOOK = NO
+DOCBOOK_OUTPUT = docbook
+GENERATE_AUTOGEN_DEF = NO
+GENERATE_PERLMOD = NO
+PERLMOD_LATEX = NO
+PERLMOD_PRETTY = YES
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION = NO
+EXPAND_ONLY_PREDEF = NO
+SEARCH_INCLUDES = YES
+SKIP_FUNCTION_MACROS = YES
+ALLEXTERNALS = NO
+EXTERNAL_GROUPS = YES
+EXTERNAL_PAGES = YES
+HIDE_UNDOC_RELATIONS = YES
+HAVE_DOT = YES
+DOT_NUM_THREADS = 0
+DOT_COMMON_ATTR = "fontname=Helvetica,fontsize=10"
+DOT_EDGE_ATTR = "labelfontname=Helvetica,labelfontsize=10"
+DOT_NODE_ATTR = "shape=box,height=0.2,width=0.4"
+CLASS_GRAPH = YES
+COLLABORATION_GRAPH = NO
+GROUP_GRAPHS = YES
+UML_LOOK = NO
+UML_LIMIT_NUM_FIELDS = 10
+DOT_UML_DETAILS = NO
+DOT_WRAP_THRESHOLD = 17
+TEMPLATE_RELATIONS = NO
+INCLUDE_GRAPH = YES
+INCLUDED_BY_GRAPH = YES
+CALL_GRAPH = NO
+CALLER_GRAPH = NO
+GRAPHICAL_HIERARCHY = YES
+DIRECTORY_GRAPH = YES
+DIR_GRAPH_MAX_DEPTH = 1
+DOT_IMAGE_FORMAT = svg
+INTERACTIVE_SVG = NO
+DOT_GRAPH_MAX_NODES = 50
+MAX_DOT_GRAPH_DEPTH = 0
+DOT_MULTI_TARGETS = NO
+GENERATE_LEGEND = YES
+DOT_CLEANUP = YES
+HTML_EXTRA_STYLESHEET = @CMAKE_BINARY_DIR@/doxygen-awesome.css
diff --git a/bindings/cpp/include/opendal.hpp b/bindings/cpp/include/opendal.hpp
index 6fd4c2379..22efc5046 100644
--- a/bindings/cpp/include/opendal.hpp
+++ b/bindings/cpp/include/opendal.hpp
@@ -28,9 +28,20 @@
namespace opendal {
+/**
+ * @class Operator
+ * @brief Operator is the entry for all public APIs.
+ */
class Operator : std::enable_shared_from_this<Operator> {
public:
Operator() = default;
+
+ /**
+ * @brief Construct a new Operator object
+ *
+ * @param scheme The scheme of the operator, same as the name of rust doc
+ * @param config The configuration of the operator, same as the service doc
+ */
Operator(std::string_view scheme,
const std::unordered_map<std::string, std::string> &config = {});
@@ -43,8 +54,27 @@ public:
Operator &operator=(Operator &&) = default;
~Operator() = default;
+ /**
+ * @brief Check if the operator is available
+ *
+ * @return true if the operator is available, false otherwise
+ */
bool available() const;
+
+ /**
+ * @brief Read data from the operator
+ *
+ * @param path The path of the data
+ * @return The data read from the operator
+ */
std::vector<uint8_t> read(std::string_view path);
+
+ /**
+ * @brief Write data to the operator
+ *
+ * @param path The path of the data
+ * @param data The data to write
+ */
void write(std::string_view path, const std::vector<uint8_t> &data);
private:
