doc: updated library doc

doc/index.rst

@@ -7,7 +7,7 @@ The project provides both a resolver library and a small daemon.
 Modular architecture of the library keeps the core tiny and efficient, and provides a state-machine like API for extensions.
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 2
 
    build
    lib

doc/lib.rst

@@ -5,25 +5,48 @@
 API reference
 =============
 
-.. doxygengroup:: resolution
-   :project: libkresolve
+.. contents::
+   :depth: 1
+   :local:
 
 .. _lib_api_rplan:
 
+Name resolution
+---------------
+
+.. doxygengroup:: resolution
+   :project: libkresolve
+
 .. doxygengroup:: rplan
    :project: libkresolve
 
+.. _lib_api_cache:
+
+Cache
+-----
+
 .. doxygengroup:: cache
    :project: libkresolve
 
+.. _lib_api_nameservers:
+
+Nameservers
+-----------
+
 .. doxygengroup:: nameservers
    :project: libkresolve
 
 .. _lib_api_modules:
 
+Modules
+-------
+
 .. doxygengroup:: modules
    :project: libkresolve
 
+Utilities
+---------
+
 .. doxygengroup:: utils
    :project: libkresolve
 

lib/README.rst

@@ -15,31 +15,6 @@ Library layout
    :local:
 
 The library as described provides basic services for name resolution, which should cover the usage.
-The following part is for those who are planning to hack on the library or develop modules, to give
-you an idea about the API and the library layout.
-
-Name resolution
----------------
-
-.. _lib_rplan:
-
-Resolution plan
----------------
-
-.. _lib_cache:
-
-Cache
------
-
-.. _lib_nameservers:
-
-Nameservers
------------
-
-Utilities
-~~~~~~~~~
-
-.. warning:: Work in progress.
 
 Resolving a name
 ----------------
@@ -64,9 +39,9 @@ the :c:func:`iterate_layer`, and the :c:func:`itercache_layer`.
 
 The library offers following services:
 
-- :ref:`Cache <lib_cache>` - MVCC cache interface for retrieving/storing resource records.
-- :ref:`Resolution plan <lib_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
-- :ref:`Nameservers <lib_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
+- :ref:`Cache <lib_api_cache>` - MVCC cache interface for retrieving/storing resource records.
+- :ref:`Resolution plan <lib_api_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
+- :ref:`Nameservers <lib_api_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
 
 A processing layer is going to be called by the query resolution driver for each query,
 so you're going to work with :ref:`struct kr_layer_param <lib_api_rplan>` as your per-query context. This structure contains pointers to

lib/generic/README.rst

@@ -6,18 +6,33 @@ such thing for C. It's either bloated, has poor interface, null-checking is abse
 doesn't allow custom allocation scheme. BSD-licensed (or compatible) code is allowed here,
 as long as it comes with a test case in `tests/test_generics.c`.
 
-Data structures
-~~~~~~~~~~~~~~~
+* array_ - a set of simple macros to make working with dynamic arrays easier.
+* map_ - a `Crit-bit tree`_ key-value map implementation (public domain) that comes with tests.
+* set_ - set abstraction implemented on top of ``map``.
+* pack_ - length-prefixed list of objects (i.e. array-list).
 
-* ``array`` - a set of simple macros to make working with dynamic arrays easier.
-* ``set`` - a `Crit-bit tree`_ simple implementation (public domain) that comes with tests.
-* ``map`` - key-value map implemented on top of ``set``.
-* ``pack`` - length-prefixed list of objects (i.e. array-list).
+array
+~~~~~
 
-API reference and examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. doxygenfile:: array.h
+   :project: libkresolve
+
+map
+~~~
+
+.. doxygenfile:: map.h
+   :project: libkresolve
+
+set
+~~~
+
+.. doxygenfile:: set.h
+   :project: libkresolve
+
+pack
+~~~~
 
-.. doxygengroup:: generics
+.. doxygenfile:: pack.h
    :project: libkresolve
 
 .. _`Crit-bit tree`: http://cr.yp.to/critbit.html 

lib/generic/array.h

@@ -15,18 +15,21 @@
  */
 
 /**
- * Generics - simple dynamic array.
  *
- * \note The C has no generics, so it is implemented mostly using macros.
+ * @file array.h
+ * @brief A set of simple macros to make working with dynamic arrays easier.
+ *
+ * @note The C has no generics, so it is implemented mostly using macros.
  * Be aware of that, as direct usage of the macros in the evaluating macros
- * may lead to different expectations, i.e.
+ * may lead to different expectations:
  *
+ *     # Undefined behaviour
  *     MIN(array_push(arr, val), other)
  *
- *  May evaluate the code twice, leading to unexpected behaviour.
- *  This is a price to pay for absence of proper generics.
+ * 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:
  *
  *      array_t(const char*) arr;
  *      array_init(arr);

lib/generic/map.h

@@ -4,11 +4,13 @@
  */
 
 /**
- * Generics - A Crit-bit tree 'map' implementation.
  *
- *  @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
+ * @file map.h
+ * @brief A Crit-bit tree key-value map implementation.
  *
- *  Example usage:
+ * @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
+ *
+ * Example usage:
  *
  *      map_t map = map_make();
  *

lib/generic/pack.h

@@ -15,34 +15,35 @@
  */
 
 /**
- * Generics - array of lenght-prefixed packed objects
+ * @file pack.h
+ * @brief A length-prefixed list of objects, also an array list.
  * 
  * Each object is prefixed by item length, unlike array this structure 
  * permits variable-length data. It is also equivallent to forward-only list
  * backed by an array.
  *
- * @note Maximum object size is 2^16 bytes, @see pack_objlen_t
+ * @note Maximum object size is 2^16 bytes, see  ::pack_objlen_t
  *
  *  Example usage:
  *
- *     pack_t pack;
- *     pack_init(pack);
+ *      pack_t pack;
+ *      pack_init(pack);
  *
- *     // Reserve 2 objects, 6 bytes total
- *     pack_reserve(pack, 2, 4 + 2);
- *
- *     // Push 2 objects
- *     pack_obj_push(pack, U8("jedi"), 4)
- *     pack_obj_push(pack, U8("\xbe\xef"), 2);
+ *      // Reserve 2 objects, 6 bytes total
+ *      pack_reserve(pack, 2, 4 + 2);
+ * 
+ *      // Push 2 objects
+ *      pack_obj_push(pack, U8("jedi"), 4)
+ *      pack_obj_push(pack, U8("\xbe\xef"), 2);
  *
- *     // Iterate length-value pairs
- *     uint8_t *it = pack_head(pack);
- *     while (it != pack_tail(pack)) {
- *         uint8_t *val = pack_obj_val(it);
- *         it = pack_obj_next(it);
- *     }
+ *      // Iterate length-value pairs
+ *      uint8_t *it = pack_head(pack);
+ *      while (it != pack_tail(pack)) {
+ *          uint8_t *val = pack_obj_val(it);
+ *          it = pack_obj_next(it);
+ *      }
  *
- *     pack_clear(pack);
+ *      pack_clear(pack);
  *
  * \addtogroup generics
  * @{
@@ -52,6 +53,10 @@
 #include <string.h>
 #include "array.h"
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
 /** Packed object length type. */
 typedef uint16_t pack_objlen_t;
 
@@ -115,4 +120,10 @@ static inline int pack_obj_push(pack_t *pack, const uint8_t *obj, pack_objlen_t
 	memcpy(endp + sizeof(len), obj, len);
 	pack->len += packed_len;
 	return 0;
-}
\ No newline at end of file
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */

lib/generic/set.h

+/*  Copyright (C) 2015 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 /**
- * Generics - A Crit-bit set implementation.
+ * @file set.h
+ * @brief A set abstraction implemented on top of map.
  *
- *  @note The API is based on @fn map.h, see it for more examples.
+ * @note The API is based on map.h, see it for more examples.
  *
- *  Example usage:
+ * Example usage:
  *
  *      set_t set = set_make();
  *
@@ -83,4 +100,4 @@ typedef int (set_walk_cb)(const char *, void *);
 }
 #endif
 
-/** @} */
\ No newline at end of file
+/** @} */

lib/rplan.h

@@ -30,7 +30,7 @@
 #include "lib/cache.h"
 #include "lib/zonecut.h"
 
-/* Query flags */
+/** Query flags */
 enum kr_query_flag {
 	QUERY_NO_MINIMIZE = 1 << 0, /**< Don't minimize QNAME. */
 	QUERY_TCP         = 1 << 1  /**< Use TCP for this query. */