doc: improved lib/build doc (apiref)

diff --git a/doc/build.rst b/doc/build.rst
index 0f7c20609becf7033dddf0f8890b427c98bf6afd..ea4877df79b10cb9bc0510be910aeb7e678b9a9c 100644 (file)
--- a/doc/build.rst
+++ b/doc/build.rst
@@ -10,14 +10,14 @@ Platform considerations
 .. csv-table::
    :header: "Project", "Platforms", "Compatibility notes"
 
-   "``daemon``", "UNIX-like [*]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
-   "``library``", "UNIX-like, Microsoft Windows [*]_ ", "MSVC_ not supported (requires ``__attribute__((cleanup))`` and GNU99), needs MinGW_"
+   "``daemon``", "UNIX-like [#]_, Microsoft Windows", "C99, libuv_ provides portable I/O"
+   "``library``", "UNIX-like, Microsoft Windows [#]_ ", "MSVC_ not supported, needs MinGW_"
    "``modules``", "*varies*", ""
-   "``unit tests``", "*equivalent to library*", ""
-   "``integration tests``", "UNIX-like", "Depends on ELF/Mach-O (flat namespace) semantics for library injection"
+   "``tests/unit``", "*equivalent to library*", ""
+   "``tests/integration``", "UNIX-like", "Depends on library injection (see [2]_)"
 
-.. [*] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
-.. [*] Modules are not supported yet, as the PE/DLL loading is different.
+.. [#] Known to be running (not exclusively) on FreeBSD, Linux and OS X.
+.. [#] Modules are not supported yet, as the PE/DLL loading is different. Library injection is working with ELF *(or Mach-O flat namespace)* only.
 
 Requirements
 ------------
@@ -29,8 +29,8 @@ the `Docker images`.
    :header: "Requirement", "Required by", "Notes"
 
    "`GNU Make`_ 3.80+", "*all*", "*(build only)*"
-   "`pkg-config`_", "*all*", "*(build only [*]_ )*"
-   "C compiler", "*all*", "*(build only)* [*]_ )"
+   "`pkg-config`_", "*all*", "*(build only)* [#]_"
+   "C compiler", "*all*", "*(build only)* [#]_"
    "libknot_ 2.0+", "*all*", "Knot DNS library."
 
 .. csv-table:: Optional requirements.
@@ -42,10 +42,10 @@ the `Docker images`.
    "GCCGO_",  "``modules/go``", "For building Go modules, see modules documentation."
    "Doxygen_", "``documentation``", "Generating API documentation."
    "Sphinx_", "``documentation``", "Building this HTML/PDF documentation."
-   "breathe_", "``documentation``", "Interfacing Doxygen API documentation to Sphinx HTML/PDF documentation."
+   "breathe_", "``documentation``", "Exposing Doxygen API doc to Sphinx."
 
-.. [*] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for dependency file generation. GCC, Clang and ICC are supported.
-.. [*] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS`` to configure dependencies manually (i.e. ``libknot_CFLAGS`` and ``libknot_LIBS``).
+.. [#] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for dependency file generation. GCC, Clang and ICC are supported.
+.. [#] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS`` to configure dependencies manually (i.e. ``libknot_CFLAGS`` and ``libknot_LIBS``).
 
 Docker image
 ~~~~~~~~~~~~
@@ -54,14 +54,14 @@ Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X)
 
 .. code-block:: bash
 
-       $ docker run cznic/knot-resolver
+   $ docker run cznic/knot-resolver
 
 See the `Docker images`_ page for more information and options.
 You can hack on the container by changing the container entrypoint to shell like:
 
 .. code-block:: bash
 
-       $ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
+   $ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
 
 Building from sources 
 ~~~~~~~~~~~~~~~~~~~~~
@@ -71,37 +71,47 @@ Several dependencies may not be in the packages yet, the script pulls and instal
 
 .. code-block:: bash
 
-       $ make info # See what's missing
+   $ make info # See what's missing
 
 You can avoid rebuilding dependencies by specifying `BUILD_IGNORE` variable, see the Dockerfile_ for example.
 Usually you only really need to rebuild `libknot`.
 
 .. code-block:: bash
-       $ export FAKEROOT="${HOME}/.local"
-       $ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
-       $ export BUILD_IGNORE="..." # Ignore installed dependencies
-       $ ./scripts/bootstrap-depends.sh ${FAKEROOT}
 
-The build system depends on `pkg-config`_ to find dependencies, but you can ignore it and force custom versions
-of the software by environment variables.
+   $ export FAKEROOT="${HOME}/.local"
+   $ export PKG_CONFIG_PATH="${FAKEROOT}/lib/pkgconfig"
+   $ export BUILD_IGNORE="..." # Ignore installed dependencies
+   $ ./scripts/bootstrap-depends.sh ${FAKEROOT}
 
-.. code-block:: bash
 
-       $ make info libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -lknot-int -ldnssec"
+.. note:: The build system relies on `pkg-config`_ to find dependencies.
+   You can override it to force custom versions of the software by environment variables.
+
+   .. code-block:: bash
+
+      $ make check libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -lknot-int -ldnssec"
 
 When you have all the dependencies ready, you can build, test and install.
 
 .. code-block:: bash
 
-       $ make
-       $ make check
-       $ make install
+   $ make
+   $ make check
+   $ make install
 
 Alternatively you can build only specific parts of the project, i.e. ``library``.
 
 .. code-block:: bash
-       $ make lib
-       $ make lib-install
+
+   $ make lib
+   $ make lib-install
+
+.. note:: Documentation is not built by default, run ``make doc`` to build it.
+
+Building extras
+~~~~~~~~~~~~~~~
+
+The project can be built with code coverage tracking using the ``COVERAGE=1`` variable.
 
 .. _Docker images: https://registry.hub.docker.com/u/cznic/knot-resolver
 .. _libuv: https://github.com/libuv/libuv
@@ -109,6 +119,7 @@ Alternatively you can build only specific parts of the project, i.e. ``library``
 .. _MinGW: http://www.mingw.org/
 .. _Dockerfile: https://registry.hub.docker.com/u/cznic/knot-resolver/dockerfile/
 
+.. _GCCGO: https://golang.org/doc/install/gccgo
 .. _Doxygen: http://www.stack.nl/~dimitri/doxygen/manual/index.html
 .. _breathe: https://github.com/michaeljones/breathe
 .. _Sphinx: http://sphinx-doc.org/

diff --git a/doc/lib.rst b/doc/lib.rst
index 422d9352859020e67c1063922eb1d68ead6830c8..a0ccdca94ab44fad92eed544f0bccddd4d544d75 100644 (file)
--- a/doc/lib.rst
+++ b/doc/lib.rst
@@ -1,7 +1,44 @@
 .. include:: ../lib/README.rst
 
-API reference
--------------
+Library layout
+--------------
 
-.. doxygenindex::
+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
+~~~~~~~~~~~~~~~
+
+.. doxygengroup:: resolution
+   :project: libkresolve
+
+Resolution plan
+~~~~~~~~~~~~~~~
+
+.. doxygengroup:: rplan
+   :project: libkresolve
+
+Cache
+~~~~~
+
+.. doxygengroup:: cache
+   :project: libkresolve
+
+Nameservers
+~~~~~~~~~~~
+
+.. doxygengroup:: nameservers
+   :project: libkresolve
+
+Modules
+~~~~~~~
+
+.. doxygengroup:: modules
+   :project: libkresolve
+
+Utilities
+~~~~~~~~~
+
+.. doxygengroup:: utils
    :project: libkresolve

diff --git a/lib/README.rst b/lib/README.rst
index 2e6e7df4d0da49cbf583124be964576f788c93f2..8852320040cdb8536fd597f6aa084749785984e6 100644 (file)
--- a/lib/README.rst
+++ b/lib/README.rst
@@ -9,16 +9,15 @@ Requirements
 Overview
 --------
 
-Resolution plan
-~~~~~~~~~~~~~~~
+Resolving a name
+~~~~~~~~~~~~~~~~
 
-Cache
-~~~~~
+.. note:: Migrating from ``getaddrinfo``
 
-Reputation
-~~~~~~~~~~
+Using cache
+~~~~~~~~~~~
 
-Modules
-~~~~~~~
+Loading modules
+~~~~~~~~~~~~~~~
 
 .. _libknot: https://gitlab.labs.nic.cz/labs/knot/tree/master/src/libknot