From: Marek Vavruša <marek.vavrusa@nic.cz>
Date: Sun, 3 May 2015 19:16:29 +0000 (+0200)
Subject: doc: updated documentation for cache backends
X-Git-Tag: v1.0.0-beta1~220^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ab3adbb0d97fcbe9e5c263ea1e2371fb97610248;p=thirdparty%2Fknot-resolver.git

doc: updated documentation for cache backends
---

diff --git a/daemon/README.rst b/daemon/README.rst
index dff2e4941..631b329ed 100644
--- a/daemon/README.rst
+++ b/daemon/README.rst
@@ -335,7 +335,21 @@ The cache in Knot DNS Resolver is persistent with LMDB backend, this means that
 the cached data on restart or crash to avoid cold-starts. The cache may be reused between cache
 daemons or manipulated from other processes, making for example synchronised load-balanced recursors possible.
 
-.. function:: cache.open(max_size)
+.. function:: cache.backends()
+
+   :return: map of backends
+
+   The cache supports runtime-changeable backends, using the optional :rfc:`3986` URI, where the scheme
+   represents backend protocol and the rest of the URI backend-specific configuration. By default, it
+   is a ``lmdb`` backend in working directory, i.e. ``lmdb://``.
+
+   Example output:
+
+   .. code-block:: lua
+
+   	[lmdb://] => true
+
+.. function:: cache.open(max_size[, config_uri])
 
    :param number max_size: Maximum cache size in bytes.
    :return: boolean
@@ -345,6 +359,13 @@ daemons or manipulated from other processes, making for example synchronised loa
 
    .. tip:: Use ``kB, MB, GB`` constants as a multiplier, e.g. ``100*MB``.
 
+   The cache supports runtime-changeable backends, see :func:`cache.backends()` for mor information and
+   default. Refer to specific documentation of specific backends for configuration string syntax.
+
+   - ``lmdb://``
+
+   As of now it only allows you to change the cache directory, e.g. ``lmdb:///tmp/cachedir``.
+
 .. function:: cache.count()
 
    :return: Number of entries in the cache.
@@ -355,13 +376,15 @@ daemons or manipulated from other processes, making for example synchronised loa
 
    Close the cache.
 
+   .. note:: This may or may not clear the cache, depending on the used backend. See :func:`cachectl.clear()`. 
 
 Timers and events
 ^^^^^^^^^^^^^^^^^
 
-The timer represents exactly the thing described in the examples - it allows you to execute closures after specified time,
-or event recurrent events. Time is always described in miliseconds, but there are convenient variables that you can use -
-``sec, minute, hour``. For example, ``5 * hour`` represents five hours, or 5*60*60*100 milliseconds.
+The timer represents exactly the thing described in the examples - it allows you to execute closures 
+after specified time, or event recurrent events. Time is always described in milliseconds,
+but there are convenient variables that you can use - ``sec, minute, hour``.
+For example, ``5 * hour`` represents five hours, or 5*60*60*100 milliseconds.
 
 .. function:: event.after(time, function)
 
diff --git a/modules/cachectl/README.rst b/modules/cachectl/README.rst
index 448049cba..abe5b5774 100644
--- a/modules/cachectl/README.rst
+++ b/modules/cachectl/README.rst
@@ -6,13 +6,14 @@ Module providing an interface to cache database, for inspection, manipulation an
 Properties
 ^^^^^^^^^^
 
-``prune``
-	Prune expired/invalid records.
+.. function:: cachectl.prune()
 
-	:Input:  N/A
-	:Output: ``{ pruned: int }``
-``clear``
-	Clear all cache records.
+  :return: ``{ pruned: int }``
 
- 	:Input:  N/A
- 	:Output: ``{ result: bool }``
+  Prune expired/invalid records.
+
+.. function:: cachectl.clear()
+
+  :return: ``{ result: bool }``
+
+  Clear all cache records.
diff --git a/modules/hints/README.rst b/modules/hints/README.rst
index b7ddf618a..0b83ced7e 100644
--- a/modules/hints/README.rst
+++ b/modules/hints/README.rst
@@ -8,20 +8,23 @@ This is a module providing static hints from ``/etc/hosts`` like file.
 Properties
 ^^^^^^^^^^
 
-``config``
-	Load specified hosts file.
+.. function:: hints.config([path])
 
-	:Input:  ``path`` i.e. ``"/etc/hosts"``
-	:Output: ``{ result: bool }``
+  :param string path:  path to hosts file, default: ``"/etc/hosts"``
+  :return: ``{ result: bool }``
+  
+  Load specified hosts file.
 
-``get``
-	Return list of address record matching given name.
+.. function:: hints.get(hostname)
 
-	:Input:  ``hostname`` i.e. ``"localhost"``
-	:Output: ``{ result: [address1, address2, ...] }``
+  :param string hostname: i.e. ``"localhost"``
+  :return: ``{ result: [address1, address2, ...] }``
 
-``set``
-	Set hostname - address hint.
+  Return list of address record matching given name.
 
- 	:Input:  ``hostname address`` i.e. ``"localhost 127.0.0.1"``
- 	:Output: ``{ result: bool }``
\ No newline at end of file
+.. function:: hints.set(pair)
+
+  :param string pair:  ``hostname address`` i.e. ``"localhost 127.0.0.1"``
+  :return: ``{ result: bool }``
+
+  Set hostname - address pair hint.