mdbx-doc: more for Doxygen (refs, build options).

Change-Id: I8b15bce3d6638a24bdafa3171ae10f01311862d7

ChangeLog.md

@@ -3,10 +3,10 @@ ChangeLog
 
 ## v0.9.x (in the development):
 - Since v0.9 usage of custom comparators and the `mdbx_dbi_open_ex()` are deprecated.
+- Support for Doxygen & [online API reference](https://erthink.github.io/libmdbx/).
 - TODO: API for explicit threads (de)registration.
 - TODO: Native bindings for C++.
 - TODO: Packages for AltLinux, Fedora/RHEL, Debian/Ubuntu.
-- TODO: support for Doxygen & online API reference.
 
 ## v0.8.2 2020-07-06:
 - Added support multi-opening the same DB in a process with SysV locking (BSD).

GNUmakefile

@@ -262,16 +262,16 @@ endef
 $(foreach section,overview mithril characteristics improvements history usage performance bindings,$(eval $(call md-extract-section,$(section),README.md)))
 
 docs/overall.md: docs/__overview.md docs/_toc.md docs/__mithril.md docs/__history.md AUTHORS LICENSE
-	echo -e "\\mainpage Overall\n\\section brief Brief" | cat - $(filter %.md, $?) > $@ && echo -e "\n\n\nLicense\n=======\n" | cat AUTHORS - LICENSE >> $@
+	echo -e "\\mainpage Overall\n\\section brief Brief" | cat - $(filter %.md, $^) > $@ && echo -e "\n\n\nLicense\n=======\n" | cat AUTHORS - LICENSE >> $@
 
 docs/intro.md: docs/_preface.md docs/__characteristics.md docs/__improvements.md docs/_restrictions.md docs/__performance.md
-	cat $? | sed 's/^Performance comparison$$/Performance comparison {#performance}/' > $@
+	cat $^ | sed 's/^Performance comparison$$/Performance comparison {#performance}/' > $@
 
 docs/usage.md: docs/__usage.md docs/_starting.md docs/__bindings.md
-	echo -e "\\page usage Usage\n\\section getting Getting the libmdbx" | cat - $? | sed 's/^Bindings$$/Bindings {#bindings}/' > $@
+	echo -e "\\page usage Usage\n\\section getting Getting the libmdbx" | cat - $^ | sed 's/^Bindings$$/Bindings {#bindings}/' > $@
 
-doxygen: docs/Doxyfile docs/overall.md docs/intro.md docs/usage.md mdbx.h ChangeLog.md AUTHORS LICENSE
+doxygen: docs/Doxyfile docs/overall.md docs/intro.md docs/usage.md mdbx.h src/options.h ChangeLog.md AUTHORS LICENSE
-	rm -rf docs/html && cp mdbx.h ChangeLog.md docs/ && (cd docs && doxygen Doxyfile) && cp AUTHORS LICENSE docs/html/
+	rm -rf docs/html && cp mdbx.h src/options.h ChangeLog.md docs/ && (cd docs && doxygen Doxyfile) && cp AUTHORS LICENSE docs/html/
 
 .PHONY: dist release-assets
 dist: libmdbx-sources-$(MDBX_VERSION_SUFFIX).tar.gz $(lastword $(MAKEFILE_LIST))

docs/Doxyfile.in

@@ -829,7 +829,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = overall.md intro.md usage.md mdbx.h ChangeLog.md
+INPUT                  = overall.md intro.md usage.md mdbx.h options.h ChangeLog.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
@@ -2153,7 +2153,7 @@ 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_SHOULD_SKIP_THIS
+PREDEFINED             = DOXYGEN
 
 # 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

docs/_starting.md

@@ -5,48 +5,48 @@ Getting started {#starting}
 > edits reflecting the improvements and enhancements were made in MDBX.
 > See Bert Hubert's [original](https://github.com/ahupowerdns/ahutils/blob/master/lmdb-semantics.md).
 
-Everything starts with an environment, created by `mdbx_env_create()`.
+Everything starts with an environment, created by \ref mdbx_env_create().
-Once created, this environment must also be opened with `mdbx_env_open()`,
+Once created, this environment must also be opened with \ref mdbx_env_open(),
-and after use be closed by `mdbx_env_close()`. At that a non-zero value of the
+and after use be closed by \ref mdbx_env_close(). At that a non-zero value
-last argument "mode" supposes MDBX will create database and directory if ones
+of the last argument "mode" supposes MDBX will create database and directory
-does not exist. In this case the non-zero "mode" argument specifies the file
+if ones does not exist. In this case the non-zero "mode" argument specifies
-mode bits be applied when a new files are created by `open()` function.
+the file mode bits be applied when a new files are created by `open()` function.
 
 Within that directory, a lock file (aka LCK-file) and a storage file (aka
 DXB-file) will be generated. If you don't want to use a directory, you can
-pass the `MDBX_NOSUBDIR` option, in which case the path you provided is used
+pass the \ref MDBX_NOSUBDIR option, in which case the path you provided is used
 directly as the DXB-file, and another file with a "-lck" suffix added
 will be used for the LCK-file.
 
 Once the environment is open, a transaction can be created within it using
-`mdbx_txn_begin()`. Transactions may be read-write or read-only, and read-write
+\ref mdbx_txn_begin(). Transactions may be read-write or read-only, and read-write
 transactions may be nested. A transaction must only be used by one thread at
 a time. Transactions are always required, even for read-only access. The
 transaction provides a consistent view of the data.
 
 Once a transaction has been created, a database (i.e. key-value space inside
-the environment) can be opened within it using `mdbx_dbi_open()`. If only one
+the environment) can be opened within it using \ref mdbx_dbi_open(). If only one
 database will ever be used in the environment, a `NULL` can be passed as the
-database name. For named databases, the `MDBX_CREATE` flag must be used to
+database name. For named databases, the \ref MDBX_CREATE flag must be used to
-create the database if it doesn't already exist. Also, `mdbx_env_set_maxdbs()`
+create the database if it doesn't already exist. Also, \ref mdbx_env_set_maxdbs()
-must be called after `mdbx_env_create()` and before `mdbx_env_open()` to set
+must be called after \ref mdbx_env_create() and before \ref mdbx_env_open() to set
 the maximum number of named databases you want to support.
 
 \note A single transaction can open multiple databases. Generally databases
 should only be opened once, by the first transaction in the process.
 
-Within a transaction, `mdbx_get()` and `mdbx_put()` can store single key-value
+Within a transaction, \ref mdbx_get() and \ref mdbx_put() can store single key-value
 pairs if that is all you need to do (but see \ref Cursors below if you want to do
 more).
 
-A key-value pair is expressed as two `MDBX_val` structures. This struct that is
+A key-value pair is expressed as two \ref MDBX_val structures. This struct that is
 exactly similar to POSIX's `struct iovec` and has two fields, `iov_len` and
 `iov_base`. The data is a `void` pointer to an array of `iov_len` bytes.
 \note The notable difference between MDBX and LMDB is that MDBX support zero
 length keys.
 
 Because MDBX is very efficient (and usually zero-copy), the data returned in
-an `MDBX_val` structure may be memory-mapped straight from disk. In other words
+an \ref MDBX_val structure may be memory-mapped straight from disk. In other words
 look but do not touch (or `free()` for that matter). Once a transaction is
 closed, the values can no longer be used, so make a copy if you need to keep
 them after that.
@@ -54,21 +54,21 @@ them after that.
 ## Cursors {#Cursors}
 To do more powerful things, we must use a cursor.
 
-Within the transaction, a cursor can be created with `mdbx_cursor_open()`.
+Within the transaction, a cursor can be created with \ref mdbx_cursor_open().
 With this cursor we can store/retrieve/delete (multiple) values using
-`mdbx_cursor_get()`, `mdbx_cursor_put()` and `mdbx_cursor_del()`.
+\ref mdbx_cursor_get(), \ref mdbx_cursor_put() and \ref mdbx_cursor_del().
 
-The `mdbx_cursor_get()` positions itself depending on the cursor operation
+The \ref mdbx_cursor_get() positions itself depending on the cursor operation
 requested, and for some operations, on the supplied key. For example, to list
-all key-value pairs in a database, use operation `MDBX_FIRST` for the first
+all key-value pairs in a database, use operation \ref MDBX_FIRST for the first
-call to `mdbx_cursor_get()`, and `MDBX_NEXT` on subsequent calls, until the end
+call to \ref mdbx_cursor_get(), and \ref MDBX_NEXT on subsequent calls, until
-is hit.
+the end is hit.
 
-To retrieve all keys starting from a specified key value, use `MDBX_SET`. For
+To retrieve all keys starting from a specified key value, use \ref MDBX_SET. For
-more cursor operations, see the API description below.
+more cursor operations, see the \ref c_api reference.
 
-When using `mdbx_cursor_put()`, either the function will position the cursor
+When using \ref mdbx_cursor_put()\ref , either the function will position the cursor
-for you based on the key, or you can use operation `MDBX_CURRENT` to use the
+for you based on the key, or you can use operation \ref MDBX_CURRENT to use the
 current position of the cursor. \note Note that key must then match the current
 position's key.
 
@@ -98,7 +98,7 @@ opened the file across all threads. The reason for this is:
    once will remove all the locks held on it, and the other instances will be
    vulnerable to corruption from other processes.
  + For compatibility with LMDB which allows multi-opening, MDBX can be
-   configured at runtime by `mdbx_setup_debug(MDBX_DBG_LEGACY_MULTIOPEN, ...)`
+   configured at runtime by \ref mdbx_setup_debug() with \ref MDBX_DBG_LEGACY_MULTIOPEN` option
    prior to calling other MDBX funcitons. In this way MDBX will track
    databases opening, detect multi-opening cases and then recover POSIX file
    locks as necessary. However, lock recovery can cause unexpected pauses,
@@ -132,24 +132,24 @@ no open MDBX-instance(s) during fork(), or atleast close it immediately after
 Do not start more than one transaction for a one thread. If you think about
 this, it's really strange to do something with two data snapshots at once,
 which may be different. MDBX checks and preventing this by returning
-corresponding error code (`MDBX_TXN_OVERLAPPING`, `MDBX_BAD_RSLOT`, `MDBX_BUSY`)
+corresponding error code (\ref MDBX_TXN_OVERLAPPING, \ref MDBX_BAD_RSLOT, \ref MDBX_BUSY)
-unless you using `MDBX_NOTLS` option on the environment. Nonetheless, with the
+unless you using \ref MDBX_NOTLS option on the environment. Nonetheless, with the
-`MDBX_NOTLS option`, you must know exactly what you are doing, otherwise you
+\ref MDBX_NOTLS option, you must know exactly what you are doing, otherwise you
 will get deadlocks or reading an alien data.
 
 Also note that a transaction is tied to one thread by default using Thread
 Local Storage. If you want to pass read-only transactions across threads,
-you can use the MDBX_NOTLS option on the environment. Nevertheless, a write
+you can use the \ref MDBX_NOTLS option on the environment. Nevertheless, a write
 transaction entirely should only be used in one thread from start to finish.
-MDBX checks this in a reasonable manner and return the MDBX_THREAD_MISMATCH
+MDBX checks this in a reasonable manner and return the \ref MDBX_THREAD_MISMATCH
 error in rules violation.
 
 
 ## Transactions, rollbacks etc
 
 To actually get anything done, a transaction must be committed using
-`mdbx_txn_commit()`. Alternatively, all of a transaction's operations
+\ref mdbx_txn_commit(). Alternatively, all of a transaction's operations
-can be discarded using `mdbx_txn_abort()`.
+can be discarded using \ref mdbx_txn_abort().
 
 \attention An important difference between MDBX and LMDB is that MDBX required
 that any opened cursors can be reused and must be freed explicitly, regardless
@@ -180,14 +180,14 @@ continue to be opened at any time.
 
 ## Duplicate keys aka Multi-values
 
-`mdbx_get()` and `mdbx_put()` respectively have no and only some support or
+\ref mdbx_get() and \ref mdbx_put() respectively have no and only some support or
 multiple key-value pairs with identical keys. If there are multiple values
-for a key, `mdbx_get()` will only return the first value.
+for a key, \ref mdbx_get() will only return the first value.
 
-When multiple values for one key are required, pass the `MDBX_DUPSORT` flag to
+When multiple values for one key are required, pass the \ref MDBX_DUPSORT flag to
-`mdbx_dbi_open()`. In an `MDBX_DUPSORT` database, by default `mdbx_put()` will
+\ref mdbx_dbi_open(). In an \ref MDBX_DUPSORT database, by default \ref mdbx_put() will
 not replace the value for a key if the key existed already. Instead it will add
-the new value to the key. In addition, `mdbx_del()` will pay attention to the
+the new value to the key. In addition, \ref mdbx_del() will pay attention to the
 value field too, allowing for specific values of a key to be deleted.
 
 Finally, additional cursor operations become available for traversing through
@@ -199,17 +199,17 @@ and retrieving duplicate values.
 If you frequently begin and abort read-only transactions, as an optimization,
 it is possible to only reset and renew a transaction.
 
-`mdbx_txn_reset()` releases any old copies of data kept around for a read-only
+\ref mdbx_txn_reset() releases any old copies of data kept around for a read-only
-transaction. To reuse this reset transaction, call `mdbx_txn_renew()` on it.
+transaction. To reuse this reset transaction, call \ref mdbx_txn_renew() on it.
-Any cursors in this transaction can also be renewed using `mdbx_cursor_renew()`
+Any cursors in this transaction can also be renewed using \ref mdbx_cursor_renew()
-or freed by `mdbx_cursor_close()`.
+or freed by \ref mdbx_cursor_close().
 
-To permanently free a transaction, reset or not, use `mdbx_txn_abort()`.
+To permanently free a transaction, reset or not, use \ref mdbx_txn_abort().
 
 
 ## Cleaning up
 
-Any created cursors must be closed using `mdbx_cursor_close()`. It is advisable
+Any created cursors must be closed using \ref mdbx_cursor_close(). It is advisable
 to repeat:
 \note An important difference between MDBX and LMDB is that MDBX required that
 any opened cursors can be reused and must be freed explicitly, regardless
@@ -225,17 +225,17 @@ avoid closing the handle while at least one transaction is using it.
 
 ## Now read up on the full API!
 
-The full MDBX documentation lists further details below, like how to:
+The full \ref c_api documentation lists further details below, like how to:
 
-- configure database size and automatic size management
+- Configure database size and automatic size management: \ref mdbx_env_set_geometry().
-- drop and clean a database
+- Drop and clean a database: \ref mdbx_drop().
-- detect and report errors
+- Detect and report errors: \ref c_err.
-- optimize (bulk) loading speed
+- Optimize (bulk) loading speed: \ref MDBX_MULTIPLE, \ref MDBX_APPEND.
-- (temporarily) reduce robustness to gain even more speed
+- Reduce (temporarily) robustness to gain even more speed: \ref sync_modes.
-- gather statistics about the database
+- Gather statistics about the database: \ref c_statinfo.
-- estimate size of range query result
+- Sstimate size of range query result: \ref c_rqest.
-- double perfomance by LIFO reclaiming on storages with write-back
+- Double perfomance by LIFO reclaiming on storages with write-back: \ref MDBX_LIFORECLAIM.
-- use sequences and canary markers
+- Use sequences and canary markers: \ref mdbx_dbi_sequence(), \ref MDBX_canary.
-- use lack-of-space callback (aka OOM-KICK)
+- Use lack-of-space callback (aka OOM-KICK): \ref mdbx_env_set_oomfunc().
-- use exclusive mode
+- Use exclusive mode: \ref MDBX_EXCLUSIVE.
-- define custom sort orders (but this is recommended to be avoided)
+- Define custom sort orders (but this is recommended to be avoided).

src/options.h

@@ -13,21 +13,51 @@
  *
  */
 
-/* Support for huge write-transactions */
+/** \defgroup build_option Build options
+ * The libmdbx build options.
+ @{ */
+
+#ifdef DOXYGEN
+/* !!! Actually this is a fake definitions     !!!
+ * !!! for documentation generation by Doxygen !!! */
+
+/** Controls enabling of debugging features.
+ *
+ *  - `MDBX_DEBUG = 0` (by default) Disables any debugging features at all,
+ *                     including logging and assertion controls.
+ *                     Logging level and corresponding debug flags changing
+ *                     by \ref mdbx_setup_debug() will not have effect.
+ *  - `MDBX_DEBUG > 0` Enables code for the debugging features (logging,
+ *                     assertions checking and internal audit).
+ *                     Simultaneously sets the default logging level
+ *                     to the `MDBX_DEBUG` value.
+ *                     Also enables \ref MDBX_DBG_AUDIT if `MDBX_DEBUG >= 2`.
+ *
+ * \ingroup build_option */
+#define MDBX_DEBUG 0...7
+
+/** Disables using of GNU libc extensions. */
+#define MDBX_DISABLE_GNU_SOURCE 0 or 1
+
+#endif /* DOXYGEN */
+
+/** Enables support for huge write-transactions */
 #ifndef MDBX_HUGE_TRANSACTIONS
 #define MDBX_HUGE_TRANSACTIONS 0
 #endif /* MDBX_HUGE_TRANSACTIONS */
 
-/* using fcntl(F_FULLFSYNC) with 5-10 times slowdown */
+/** Using fcntl(F_FULLFSYNC) with 5-10 times slowdown */
 #define MDBX_OSX_WANNA_DURABILITY 0
-/* using fsync() with chance of data lost on power failure */
+/** Using fsync() with chance of data lost on power failure */
 #define MDBX_OSX_WANNA_SPEED 1
 
 #ifndef MDBX_OSX_SPEED_INSTEADOF_DURABILITY
+/** Choices \ref MDBX_OSX_WANNA_DURABILITY or \ref MDBX_OSX_WANNA_SPEED
+ * for OSX & iOS */
 #define MDBX_OSX_SPEED_INSTEADOF_DURABILITY MDBX_OSX_WANNA_DURABILITY
 #endif /* MDBX_OSX_SPEED_INSTEADOF_DURABILITY */
 
-/* Controls checking PID against reuse DB environment after the fork() */
+/** Controls checking PID against reuse DB environment after the fork() */
 #ifndef MDBX_TXN_CHECKPID
 #if defined(MADV_DONTFORK) || defined(_WIN32) || defined(_WIN64)
 /* PID check could be ommited:
@@ -43,7 +73,7 @@
 #define MDBX_TXN_CHECKPID_CONFIG STRINGIFY(MDBX_TXN_CHECKPID)
 #endif /* MDBX_TXN_CHECKPID */
 
-/* Controls checking transaction owner thread against misuse transactions from
+/** Controls checking transaction owner thread against misuse transactions from
  * other threads. */
 #ifndef MDBX_TXN_CHECKOWNER
 #define MDBX_TXN_CHECKOWNER 1
@@ -52,7 +82,7 @@
 #define MDBX_TXN_CHECKOWNER_CONFIG STRINGIFY(MDBX_TXN_CHECKOWNER)
 #endif /* MDBX_TXN_CHECKOWNER */
 
-/* Does a system have battery-backed Real-Time Clock or just a fake. */
+/** Does a system have battery-backed Real-Time Clock or just a fake. */
 #ifndef MDBX_TRUST_RTC
 #if defined(__linux__) || defined(__gnu_linux__) || defined(__NetBSD__) ||     \
     defined(__OpenBSD__)
@@ -67,13 +97,25 @@
 
 //------------------------------------------------------------------------------
 
-#define MDBX_LOCKING_WIN32FILES -1  /* Win32 File Locking API */
+/** Win32 File Locking API for \ref MDBX_LOCKING */
-#define MDBX_LOCKING_SYSV 5         /* SystemV IPC semaphores */
+#define MDBX_LOCKING_WIN32FILES -1
-#define MDBX_LOCKING_POSIX1988 1988 /* POSIX-1 Shared anonymous semaphores */
-#define MDBX_LOCKING_POSIX2001 2001 /* POSIX-2001 Shared Mutexes */
-#define MDBX_LOCKING_POSIX2008 2008 /* POSIX-2008 Robust Mutexes */
-#define MDBX_LOCKING_BENAPHORE 1995 /* BeOS Benaphores, aka Futexes */
 
+/** SystemV IPC semaphores for \ref MDBX_LOCKING */
+#define MDBX_LOCKING_SYSV 5
+
+/** POSIX-1 Shared anonymous semaphores for \ref MDBX_LOCKING */
+#define MDBX_LOCKING_POSIX1988 1988
+
+/** POSIX-2001 Shared Mutexes for \ref MDBX_LOCKING */
+#define MDBX_LOCKING_POSIX2001 2001
+
+/** POSIX-2008 Robust Mutexes for \ref MDBX_LOCKING */
+#define MDBX_LOCKING_POSIX2008 2008
+
+/** BeOS Benaphores, aka Futexes for \ref MDBX_LOCKING */
+#define MDBX_LOCKING_BENAPHORE 1995
+
+/** Advanced: Choices the locking implementation (autodetection by default). */
 #if defined(_WIN32) || defined(_WIN64)
 #define MDBX_LOCKING MDBX_LOCKING_WIN32FILES
 #else
@@ -106,6 +148,7 @@
 #endif /* MDBX_LOCKING */
 #endif /* !Windows */
 
+/** Advanced: Using POSIX OFD-locks (autodetection by default). */
 #ifndef MDBX_USE_OFDLOCKS
 #if defined(F_OFD_SETLK) && defined(F_OFD_SETLKW) && defined(F_OFD_GETLK) &&   \
     !defined(MDBX_SAFE4QEMU) &&                                                \
@@ -123,7 +166,7 @@
 
 #ifndef MDBX_CPU_WRITEBACK_INCOHERENT
 #if defined(__ia32__) || defined(__e2k__) || defined(__hppa) ||                \
-    defined(__hppa__)
+    defined(__hppa__) || defined(DOXYGEN)
 #define MDBX_CPU_WRITEBACK_INCOHERENT 0
 #else
 #define MDBX_CPU_WRITEBACK_INCOHERENT 1
@@ -151,7 +194,7 @@
 #endif /* MDBX_MMAP_INCOHERENT_CPU_CACHE */
 
 #ifndef MDBX_64BIT_ATOMIC
-#if MDBX_WORDBITS >= 64
+#if MDBX_WORDBITS >= 64 || defined(DOXYGEN)
 #define MDBX_64BIT_ATOMIC 1
 #else
 #define MDBX_64BIT_ATOMIC 0
@@ -180,7 +223,7 @@
 #else
 #define MDBX_64BIT_CAS 0
 #endif
-#elif defined(_MSC_VER) || defined(__APPLE__)
+#elif defined(_MSC_VER) || defined(__APPLE__) || defined(DOXYGEN)
 #define MDBX_64BIT_CAS 1
 #else
 #define MDBX_64BIT_CAS MDBX_64BIT_ATOMIC
@@ -213,6 +256,7 @@
 #endif
 #endif /* MDBX_CACHELINE_SIZE */
 
+/** @} end of build options */
 /*******************************************************************************
  *******************************************************************************
  ******************************************************************************/