[3918] Documentation updated.

doc/Makefile.am

@@ -4,6 +4,7 @@ EXTRA_DIST  = version.ent.in differences.txt Doxyfile Doxyfile-xml
 EXTRA_DIST += devel/config-backend.dox
 EXTRA_DIST += devel/contribute.dox
 EXTRA_DIST += devel/mainpage.dox
+EXTRA_DIST += devel/qa.dox
 
 EXTRA_DIST += images/isc-logo.png
 

doc/devel/contribute.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013,2015  Internet Systems Consortium, Inc. ("ISC")
 //
 // Permission to use, copy, modify, and/or distribute this software for any
 // purpose with or without fee is hereby granted, provided that the above
@@ -78,33 +78,7 @@ change. That is even more true for new code: if you write a new
 function, method or a class, you definitely should write unit-tests
 for it.
 
-Kea uses the Google C++ Testing Framework (also called googletest or
+See @ref qaUnitTests for instructions on how to run unit-tests.
-gtest) as a base for our C++ unit-tests. See
-http://code.google.com/p/googletest/ for details. We still have some Python
-unit-tests that we inherited from BIND10 days, but those tests are being
-removed, so please do not develop any new Python tests in Kea. (If you
-want to write DHCP tests in Python, we encourage you to take a look
-at ISC Forge: http://kea.isc.org/wiki/IscForge). You must
-have \c gtest installed or at least extracted in a directory before
-compiling Kea unit-tests. To enable unit-tests in Kea, use:
-
-@code
-./configure --with-gtest=/path/to/your/gtest/dir
-@endcode
-
-or
-
-@code
-./configure --with-gtest-source=/path/to/your/gtest/dir
-@endcode
-
-Depending on how you compiled or installed \c gtest (e.g. from sources
-or using some package management system) one of those two switches will
-find \c gtest. After that you make run unit-tests:
-
-@code
-make check
-@endcode
 
 If you happen to add new files or have modified any \c Makefile.am
 files, it is also a good idea to check if you haven't broken the
@@ -162,8 +136,9 @@ critical for whatever reason, it may also be mentioned in release notes.
 @section contributorGuideExtra Extra steps
 
 If you are interested in knowing the results of more in-depth testing,
-you are welcome to visit the Kea build farm:
+you are welcome to visit the ISC Jenkins page: https://jenkins.isc.org
-http://git.kea.isc.org/~tester/builder/KEA-builder-new.html.  This is a
+(Our old Kea build farm http://git.kea.isc.org/~tester/builder/KEA-builder-new.html
+is being migrated to Jenkins).  This is a
 live result page with all tests being run on various systems.  Besides
 basic unit-tests, we also have reports from valgrind (memory debugger),
 cppcheck and clang-analyzer (static code analyzers), Lettuce system

doc/devel/mainpage.dox

@@ -105,6 +105,9 @@
  *   - @subpage configBackendAdding
  * - @subpage perfdhcpInternals
  *
+ * @section qa Quality Assurance
+ *   - @subpage qaUnitTests
+ *
  * @section miscellaneousTopics Miscellaneous Topics
  * - @subpage logKeaLogging
  *   - @subpage logBasicIdeas

doc/devel/qa.dox

@@ -0,0 +1,71 @@
+// Copyright (C) 2015  Internet Systems Consortium, Inc. ("ISC")
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
+// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+/**
+
+@page qa Kea Quality Assurance processes
+
+ @section qaUnitTests Unit-tests
+
+Kea uses the Google C++ Testing Framework (also called googletest or gtest) as a
+base for our C++ unit-tests. See http://code.google.com/p/googletest/ for
+details. We used to have Python unit-tests that were inherited from BIND10
+days. Those tests are removed now, so please do not develop any new Python
+tests in Kea. If you want to write DHCP tests in Python, we encourage you to
+take a look at ISC Forge: http://kea.isc.org/wiki/IscForge. You must have \c
+gtest installed or at least extracted in a directory before compiling Kea
+unit-tests. To enable unit-tests in Kea, use:
+
+@code
+./configure --with-gtest=/path/to/your/gtest/dir
+@endcode
+
+or
+
+@code
+./configure --with-gtest-source=/path/to/your/gtest/dir
+@endcode
+
+Depending on how you compiled or installed \c gtest (e.g. from sources
+or using some package management system) one of those two switches will
+find \c gtest. After that you make run unit-tests:
+
+@code
+make check
+
+@endcode
+
+The following environment variable can affect unit-tests:
+
+- KEA_SOCKET_TEST_DIR - if set, it specifies the directory where Unix
+  sockets are created. There's OS limitation on how long a Unix socket
+  path can be. It is typcially slightly over 100 characters. If you
+  happen to build and run unit-tests in deeply nested directories, this
+  may become a problem. KEA_SOCKET_TEST_DIR can be specified to instruct
+  unit-test to use a different directory. Must not end with slash (e.g.
+  /tmp).
+
+- KEA_LOCKFILE_DIR - Specifies a directory where the logging system should
+  create its lock file. If not specified, it is prefix/var/run/kea, where prefix
+  defaults to /usr/local. This variable must not end with a slash. There is one
+  special value: "none", which instructs Kea to not create lock file at
+  all. This may cause issues if several processes log to the same file.
+  Also see Kea User's Guide, section 15.3.
+
+- KEA_LOGGER_DESTINATION - Specifies logging destination. If not set, logged
+  messages will not be recorded anywhere. There are 3 special values:
+  stdout, stderr and syslog. Any other value is interpreted as a filename.
+  Also see Kea User's Guide, section 15.3.
+
+ */

doc/guide/dhcp4-srv.xml

@@ -2876,11 +2876,12 @@ temporarily override a list of interface names and listen on all interfaces.
       </para>
 
       <para>
-        The total path is limited to the size of sun_path field of the
+	The length of the path specified by the <command>socket-name</command>
-        sockaddr_un structure of your system, decreased by one. That's 107 bytes
+	parameter is restricted by the maximum length for the unix socket name
-        on Linux and 103 bytes on FreeBSD. Other systems are expected to have
+	on your operating system, i.e. the size of the <command>sun_path</command>
-        similar limitations. Please check documentation of your operating system
+	field in the <command>sockaddr_un</command> structure, decreased by 1.
-        for details. In case of failure, please specify shorter path.
+	This value varies on different operating systems between 91 and 107
+	characters. The typical values are 107 on Linux and 103 on FreeBSD.
       </para>
 
       <para>

doc/guide/dhcp6-srv.xml

@@ -2864,11 +2864,12 @@ should include options from the isc option space:
       </para>
 
       <para>
-        The total path is limited to the size of sun_path field of the
+	The length of the path specified by the <command>socket-name</command>
-        sockaddr_un structure of your system, decreased by one. That's 107 bytes
+	parameter is restricted by the maximum length for the unix socket name
-        on Linux and 103 bytes on FreeBSD. Other systems are expected to have
+	on your operating system, i.e. the size of the <command>sun_path</command>
-        similar limitations. Please check documentation of your operating system
+	field in the <command>sockaddr_un</command> structure, decreased by 1.
-        for details. In case of failure, please specify shorter path.
+	This value varies on different operating systems between 91 and 107
+	characters. The typical values are 107 on Linux and 103 on FreeBSD.
       </para>
 
       <para>