From 9c569b41ed709717b084aab8789721fa817428d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9B=D0=B5=D0=BE=D0=BD=D0=B8=D0=B4=20=D0=AE=D1=80=D1=8C?= =?UTF-8?q?=D0=B5=D0=B2=20=28Leonid=20Yuriev=29?= Date: Sat, 23 Apr 2022 17:50:28 +0300 Subject: [PATCH] mdbx-docs: fix/refine `C++ API` docs by Doxygen. --- docs/Doxyfile.in | 20 +++++++++++++++----- mdbx.h | 19 ++++++++++--------- mdbx.h++ | 26 ++++++++++++++++++++++---- 3 files changed, 47 insertions(+), 18 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index e46a8afd..e23678eb 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -424,7 +424,7 @@ SUBGROUPING = YES # SEPARATE_MEMBER_PAGES. # The default value is: NO. -INLINE_GROUPED_CLASSES = NO +INLINE_GROUPED_CLASSES = YES # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in @@ -434,7 +434,7 @@ INLINE_GROUPED_CLASSES = NO # Man pages) or section (for LaTeX and RTF). # The default value is: NO. -INLINE_SIMPLE_STRUCTS = NO +INLINE_SIMPLE_STRUCTS = YES # When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or # enum is documented as struct, union, or enum with the name of the typedef. So @@ -660,7 +660,7 @@ SORT_BRIEF_DOCS = NO # detailed member documentation. # The default value is: NO. -SORT_MEMBERS_CTORS_1ST = NO +SORT_MEMBERS_CTORS_1ST = YES # If the SORT_GROUP_NAMES tag is set to YES then doxygen will sort the hierarchy # of group names into alphabetical order. If set to NO the group names will @@ -941,7 +941,12 @@ EXCLUDE_PATTERNS = # Note that the wildcards are matched against the file with absolute path, so to # exclude all test directories use the pattern */test/* -EXCLUDE_SYMBOLS = +EXCLUDE_SYMBOLS = NOMINMAX __ORDER_BIG_ENDIAN__ __ORDER_LITTLE_ENDIAN__ \ + __has_include __has_attribute __has_builtin __has_cpp_attribute __has_extension __has_feature \ + HAVE_STRUCT_IOVEC MDBX_STRINGIFY_HELPER MDBX_STRINGIFY \ + MDBX_NOSANITIZE_ENUM MDBX_PRINTF_ARGS \ + CONSTEXPR_ENUM_FLAGS_OPERATIONS DEFINE_ENUM_FLAG_OPERATORS \ + bool false true __dll_export __dll_import # The EXAMPLE_PATH tag can be used to specify one or more files or directories # that contain example code fragments that are included (see the \include @@ -2216,7 +2221,12 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = DOXYGEN +PREDEFINED = DOXYGEN MDBX_DECLARE_EXCEPTION \ + MDBX_CXX01_CONSTEXPR MDBX_CXX01_CONSTEXPR_VAR \ + MDBX_CXX11_CONSTEXPR MDBX_CXX11_CONSTEXPR_VAR \ + MDBX_CXX14_CONSTEXPR MDBX_CXX14_CONSTEXPR_VAR \ + MDBX_CXX17_CONSTEXPR MDBX_CXX20_CONSTEXPR \ + MDBX_CXX17_NOEXCEPT # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/mdbx.h b/mdbx.h index 2fc7e2de..322de0fb 100644 --- a/mdbx.h +++ b/mdbx.h @@ -209,7 +209,8 @@ typedef mode_t mdbx_mode_t; #pragma warning(pop) #endif -/** @} close c_api +/** end of c_api @} + * * \defgroup api_macros Common Macros * @{ */ @@ -574,7 +575,7 @@ typedef mode_t mdbx_mode_t; #endif /* DEFINE_ENUM_FLAG_OPERATORS */ -/** @} end of Common Macros */ +/** end of api_macros @} */ /*----------------------------------------------------------------------------*/ @@ -961,7 +962,7 @@ LIBMDBX_API const char *mdbx_dump_val(const MDBX_val *key, char *const buf, /** \brief Panics with message and causes abnormal process termination. */ LIBMDBX_API void mdbx_panic(const char *fmt, ...) MDBX_PRINTF_ARGS(1, 2); -/** @} end of logging & debug */ +/** end of c_debug @} */ /** \brief Environment flags * \ingroup c_opening @@ -1361,7 +1362,7 @@ enum MDBX_env_flags_t { * \ref mdbx_txn_begin() for particular write transaction. \see sync_modes */ MDBX_UTTERLY_NOSYNC = MDBX_SAFE_NOSYNC | UINT32_C(0x100000), - /** @} end of SYNC MODES */ + /** end of sync_modes @} */ }; #ifndef __cplusplus /** \ingroup c_opening */ @@ -3806,7 +3807,7 @@ MDBX_NOTHROW_CONST_FUNCTION LIBMDBX_INLINE_API(uint32_t, mdbx_key_from_int32, (const int32_t i32)) { return UINT32_C(0x80000000) + i32; } -/** @} */ +/** end of value2key @} */ /** \defgroup key2value Key-to-Value functions * \brief Key-to-Value functions to @@ -3827,7 +3828,7 @@ mdbx_int32_from_key(const MDBX_val); MDBX_NOTHROW_PURE_FUNCTION LIBMDBX_API int64_t mdbx_int64_from_key(const MDBX_val); -/** @} */ +/** end of value2key @} */ /** \brief Retrieve statistics for a database. * \ingroup c_statinfo @@ -5100,7 +5101,7 @@ LIBMDBX_API int mdbx_env_open_for_recovery(MDBX_env *env, const char *pathname, * leg(s). */ LIBMDBX_API int mdbx_env_turn_for_recovery(MDBX_env *env, unsigned target_meta); -/** @} B-tree Traversal */ +/** end of btree_traversal @} */ /**** Attribute support functions for Nexenta (scheduled for removal) * *****************************************************************/ @@ -5270,10 +5271,10 @@ LIBMDBX_API int mdbx_cursor_get_attr(MDBX_cursor *cursor, MDBX_val *key, * \retval MDBX_EINVAL An invalid parameter was specified. */ LIBMDBX_API int mdbx_get_attr(MDBX_txn *txn, MDBX_dbi dbi, MDBX_val *key, MDBX_val *data, mdbx_attr_t *pattr); -/** @} end of Attribute support functions for Nexenta */ +/** end of nexenta @} */ #endif /* MDBX_NEXENTA_ATTRS */ -/** @} end of C API */ +/** end of c_api @} */ /******************************************************************************* * Workaround for mmaped-lookahead-cross-page-boundary bug diff --git a/mdbx.h++ b/mdbx.h++ index 11d209e6..53b85adb 100644 --- a/mdbx.h++ +++ b/mdbx.h++ @@ -256,11 +256,13 @@ #endif /* _MSC_VER (warnings) */ //------------------------------------------------------------------------------ +/// \brief The libmdbx C++ API namespace +/// \ingroup cxx_api +namespace mdbx { + /// \defgroup cxx_api C++ API /// @{ -namespace mdbx { - // Functions whose signature depends on the `mdbx::byte` type // must be strictly defined as inline! #if defined(DOXYGEN) || (defined(__cpp_char8_t) && __cpp_char8_t >= 201811) @@ -352,6 +354,9 @@ using path = ::std::wstring; using path = ::std::string; #endif /* mdbx::path */ +/// \defgroup cxx_exceptions exceptions and errors +/// @{ + /// \brief Transfers C++ exceptions thru C callbacks. /// \details Implements saving exceptions before returning /// from an C++'s environment to the intermediate C code and re-throwing after @@ -507,11 +512,17 @@ static MDBX_CXX14_CONSTEXPR size_t check_length(size_t headroom, size_t payload); static MDBX_CXX14_CONSTEXPR size_t check_length(size_t headroom, size_t payload, size_t tailroom); + +/// end of cxx_exceptions @} + static MDBX_CXX17_CONSTEXPR size_t strlen(const char *c_str) noexcept; static MDBX_CXX20_CONSTEXPR void *memcpy(void *dest, const void *src, size_t bytes) noexcept; //------------------------------------------------------------------------------ +/// \defgroup cxx_data slices and buffers +/// @{ + #if MDBX_HAVE_CXX20_CONCEPTS template @@ -2741,6 +2752,8 @@ struct pair_result : public pair { } }; +/// end of cxx_data @} + //------------------------------------------------------------------------------ /// \brief Loop control constants for readers enumeration functor and other @@ -5877,12 +5890,18 @@ inline bool cursor::erase(const slice &key, const slice &value) { return data.done && erase(); } +/// end cxx_api @} } // namespace mdbx //------------------------------------------------------------------------------ +/// \brief The `std:: namespace part of libmdbx C++ API +/// \ingroup cxx_api namespace std { +/// \defgroup cxx_api C++ API +/// @{ + inline string to_string(const ::mdbx::slice &value) { ostringstream out; out << value; @@ -5974,10 +5993,9 @@ template <> struct hash<::mdbx::slice> { } }; +/// end cxx_api @} } // namespace std #ifdef _MSC_VER #pragma warning(pop) #endif - -/// @} end of C++ API