doc: updated API doc and examples

diff --git a/doc/lib.rst b/doc/lib.rst
index c89712bd4548a74d7015d6154d9eb93b5ae7b7ba..5aec08f256609657313a6619d68e7e6fa1fe09fd 100644 (file)
--- a/doc/lib.rst
+++ b/doc/lib.rst
@@ -14,10 +14,9 @@ API reference
 Name resolution
 ---------------
 
-.. doxygengroup:: resolution
+.. doxygenfile:: resolve.h
    :project: libkresolve
-
-.. doxygengroup:: rplan
+.. doxygenfile:: rplan.h
    :project: libkresolve
 
 .. _lib_api_cache:
@@ -25,7 +24,7 @@ Name resolution
 Cache
 -----
 
-.. doxygengroup:: cache
+.. doxygenfile:: cache.h
    :project: libkresolve
 
 .. _lib_api_nameservers:
@@ -33,7 +32,9 @@ Cache
 Nameservers
 -----------
 
-.. doxygengroup:: nameservers
+.. doxygenfile:: nsrep.h
+   :project: libkresolve
+.. doxygenfile:: zonecut.h
    :project: libkresolve
 
 .. _lib_api_modules:
@@ -41,13 +42,15 @@ Nameservers
 Modules
 -------
 
-.. doxygengroup:: modules
+.. doxygenfile:: module.h
    :project: libkresolve
 
 Utilities
 ---------
 
-.. doxygengroup:: utils
+.. doxygenfile:: utils.h
+   :project: libkresolve
+.. doxygenfile:: defines.h
    :project: libkresolve
 
 .. _lib_generics:

diff --git a/lib/cache.h b/lib/cache.h
index 371a48f2e71ca6d20039d556081c18c87c137af1..ba658d78cd8efcca115ee4502d0e0a54aaefeea8 100644 (file)
--- a/lib/cache.h
+++ b/lib/cache.h
@@ -14,9 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup cache
- * @{
- */
 #pragma once
 
 #include <libknot/rrset.h>
@@ -117,5 +114,3 @@ int kr_cache_remove(namedb_txn_t *txn, const knot_rrset_t *rr);
  * @return KNOT_E*
  */
 int kr_cache_clear(namedb_txn_t *txn);
-
-/** @} */

diff --git a/lib/defines.h b/lib/defines.h
index 159a13833beccb4656694d3ae4825b44b985eb24..141f219557df72af09e1b7b5f38297ec84595925 100644 (file)
--- a/lib/defines.h
+++ b/lib/defines.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup utils
- * @{
- */
-
 #pragma once
 
 #include <errno.h>
@@ -51,5 +47,3 @@
 #define KR_EDNS_VERSION 0
 #define KR_EDNS_PAYLOAD 4096
 /* @endcond */
-
-/** @} */

diff --git a/lib/generic/array.h b/lib/generic/array.h
index eb844fff94851b4dd0f41b137bc7c82313c65bb3..5655396f15a19110790b1e0ec6102acdd98790bd 100644 (file)
--- a/lib/generic/array.h
+++ b/lib/generic/array.h
@@ -23,14 +23,16 @@
  * Be aware of that, as direct usage of the macros in the evaluating macros
  * may lead to different expectations:
  *
- *     # Undefined behaviour
+ * @code{.c}
  *     MIN(array_push(arr, val), other)
+ * @endcode
  *
  * May evaluate the code twice, leading to unexpected behaviour.
  * This is a price to pay for the absence of proper generics.
  *
- * Example usage:
+ * # Example usage:
  *
+ * @code{.c}
  *      array_t(const char*) arr;
  *      array_init(arr);
  *
@@ -55,7 +57,7 @@
  *
  *      // Random delete
  *      array_del(arr, 0);
- *
+ * @endcode
  * \addtogroup generics
  * @{
  */

diff --git a/lib/generic/map.h b/lib/generic/map.h
index 7b04af51095de2b5d9675ba492ce6fae45b29dc3..7d40f9b528bb4f19718fc0a19c14a5d491fa3027 100644 (file)
--- a/lib/generic/map.h
+++ b/lib/generic/map.h
@@ -9,8 +9,9 @@
  *
  * @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
  *
- * Example usage:
+ * # Example usage:
  *
+ * @code{.c}
  *      map_t map = map_make();
  *
  *      // Custom allocator (optional)
@@ -43,6 +44,7 @@
  *
  *      // Clear the map
  *      map_clear(&map);
+ * @endcode
  *
  * \addtogroup generics
  * @{

diff --git a/lib/generic/pack.h b/lib/generic/pack.h
index bd3a8a774444b53016c11cf24a813e1beb1e442b..1fcdc616ce74d4d6f21f8b09ec8e2fe9b7958e4d 100644 (file)
--- a/lib/generic/pack.h
+++ b/lib/generic/pack.h
@@ -24,8 +24,9 @@
  *
  * @note Maximum object size is 2^16 bytes, see  ::pack_objlen_t
  *
- *  Example usage:
+ * # Example usage:
  *
+ * @code{.c}
  *      pack_t pack;
  *      pack_init(pack);
  *
@@ -47,6 +48,7 @@
  *      pack_obj_del(pack, U8("jedi"), 4);
  *
  *      pack_clear(pack);
+ * @endcode
  *
  * \addtogroup generics
  * @{

diff --git a/lib/generic/set.h b/lib/generic/set.h
index 26a3d36a08056494fdf8f3553159738ac692e9f8..be5be1602a7b54656014208fb37a63c4bc17d45a 100644 (file)
--- a/lib/generic/set.h
+++ b/lib/generic/set.h
@@ -20,8 +20,9 @@
  *
  * @note The API is based on map.h, see it for more examples.
  *
- * Example usage:
+ * # Example usage:
  *
+ * @code{.c}
  *      set_t set = set_make();
  *
  *      // Insert keys
@@ -50,6 +51,7 @@
  *
  *      // Clear the set
  *      set_clear(&set);
+ * @endcode
  *
  * \addtogroup generics
  * @{

diff --git a/lib/layer.h b/lib/layer.h
index e812efc72b8dfffec4962dd42638408f5f0bbb61..0f7f314abf072181ee0888a16a8105fcf3aa98de 100644 (file)
--- a/lib/layer.h
+++ b/lib/layer.h
@@ -16,10 +16,6 @@
 
 #pragma once
 
-/** \addtogroup rplan
- * @{
- */
-
 #include "lib/defines.h"
 #include "lib/resolve.h"
 
@@ -32,6 +28,4 @@
     } while (0)
 #else
  #define QRDEBUG(query, cls, fmt, ...)
-#endif
-
-/** @} */
+#endif
\ No newline at end of file

diff --git a/lib/module.h b/lib/module.h
index bca4d3c626bab755a22bff2eef1d1106deda1afc..2b8c9c7eff5d97e6f02e20895db4b0a258491fc6 100644 (file)
--- a/lib/module.h
+++ b/lib/module.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup modules
- * @{
- */
-
 #pragma once
 
 #include <libknot/processing/layer.h>
@@ -92,5 +88,3 @@ void kr_module_unload(struct kr_module *module);
  */
 #define KR_MODULE_EXPORT(module) \
     uint32_t module ## _api() { return KR_MODULE_API; }
-
-/** @} */

diff --git a/lib/nsrep.h b/lib/nsrep.h
index e0f25d772d65f60d554c44fc2a0c0b1a05cecf45..13cdef59ecb1fd9bdd051c2c1bcf21e542ab6bbf 100644 (file)
--- a/lib/nsrep.h
+++ b/lib/nsrep.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup nameservers
- * @{
- */
-
 #pragma once
 
 #include <netinet/in.h>
@@ -64,5 +60,3 @@ struct kr_nsrep
  * @return       score, see enum kr_ns_score
  */
 int kr_nsrep_elect(struct kr_nsrep *ns, map_t *nsset);
-
-/** @} */

diff --git a/lib/rplan.h b/lib/rplan.h
index fc4fe1a0ae68f39f29147e34cf30cac88a5df937..07aa951fa1d74eca53268afc2643898e984dbd49 100644 (file)
--- a/lib/rplan.h
+++ b/lib/rplan.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup rplan
- * @{
- */
-
 #pragma once
 
 #include <sys/time.h>
@@ -141,5 +137,3 @@ struct kr_query *kr_rplan_current(struct kr_rplan *rplan);
  * Return true if resolution chain satisfies given query.
  */
 bool kr_rplan_satisfies(struct kr_query *closure, const knot_dname_t *name, uint16_t cls, uint16_t type);
-
-/** @} */

diff --git a/lib/utils.h b/lib/utils.h
index 24f8c4af2ce0c4751655dcf321dc0e17e00a9292..219b662a770bf352909b7cdbd6eba94073409ab4 100644 (file)
--- a/lib/utils.h
+++ b/lib/utils.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup utils
- * @{
- */
-
 #pragma once
 
 #include <stdio.h>
@@ -40,5 +36,3 @@ extern void _cleanup_fclose(FILE **p);
 
 /** Concatenate N strings. */
 char* kr_strcatdup(unsigned n, ...);
-
-/** @} */

diff --git a/lib/zonecut.h b/lib/zonecut.h
index 4022198c92365cae485b0635ebe654ce671db03c..fd708c1b0577fa6a577a0df4233945751c12b3ac 100644 (file)
--- a/lib/zonecut.h
+++ b/lib/zonecut.h
@@ -14,10 +14,6 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-/** \addtogroup rplan
- * @{
- */
-
 #pragma once
 
 #include "lib/generic/map.h"
@@ -109,5 +105,3 @@ int kr_zonecut_set_sbelt(struct kr_zonecut *cut);
  * @return 0 or error code
  */
 int kr_zonecut_find_cached(struct kr_zonecut *cut, namedb_txn_t *txn, uint32_t timestamp);
-
-/** @} */