doc: updated API doc and examples

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:

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);
-
-/** @} */

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 */
-
-/** @} */

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
  * @{
  */

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
  * @{

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
  * @{

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
  * @{

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

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; }
-
-/** @} */

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);
-
-/** @} */

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);
-
-/** @} */

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, ...);
-
-/** @} */

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);
-
-/** @} */