[3484] Miscellanous editing changes during review

Correction of typos/grammatical errors etc.  Also included text in the
contributors' section explaining why test-driven development is used.

doc/devel/contribute.dox

@@ -76,12 +76,31 @@ almost every line of code. Even if you are fixing something small,
 like a single line fix, you are encouraged to write unit-tests for that
 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. To ensure that the test for the specific change is valid, it
-should be written before the change is applied. The test should initially
-fail. When the change is applied the test should start passing. The
-test validating a new function should be written against empty
-(unimplemented) function. When the function is implemented, the test
-should pass.
+for it.
+
+To ensure that everything is tested, ISC uses a development method
+called Test Driven Development (TDD).  In TDD, a feature is developed
+alongside the tests, with the tests being written first.  In detail,
+a test is written for a small piece of functionality and run against
+the existing code. (In the case where the test is a unit test for
+a function, it would be run against an empty (unimplemented)
+function.)  The test should fail.  A minimal amount of code is then
+written, just enough to get the test to pass.  Then the process is
+repeated for the next small piece of functionality. This continues
+until all the functionality has been implemented.
+
+This approach has two advantages:
+
+- By writing a test first and then only enough code to pass the
+test, that code is fully tested.  By repeating this process until
+the feature is fully implemented, all the code gets test coverage.
+You avoid the situation where not enough tests have been written
+to check all the code.
+
+- By running the test before the code implementing the function is
+written and observing the test fail, you can detect the situation
+where a bug in the test code will cause it to pass regardless of
+the code being tested.
 
 See @ref qaUnitTests for instructions on how to run unit-tests.
 

doc/devel/mainpage.dox

@@ -31,7 +31,7 @@
  * If you are a user or system administrator, rather than software engineer,
  * you should read the
  * <a href="http://kea.isc.org/docs/kea-guide.html">Kea
- * Administrator Reference Manual</a> instead. If you are using Beta or
+ * Administrator Reference Manual</a> instead. If you are using a beta or
  * development version of Kea, the
  * <a href="http://git.kea.isc.org/~tester/kea/guide/kea-guide.html">
  * development version of the manual</a> is recommended.

src/bin/dhcp4/dhcp4.dox

@@ -57,7 +57,7 @@ applies to all subnets. However, some subnets may have it overwritten with subne
 specific values that takes precedence over global values that are considered
 defaults. The parameters inheritance is implemented by means of the "global
 context". The global context is represented by the @ref isc::dhcp::ParserContext
-class and it holds pointers to storages of different kind, e.g. text parameters,
+class and it holds pointers to storage of different kinds, e.g. text parameters,
 numeric parameters etc. When the server is parsing the top level configuration
 parameters it passes pointers to the storages of the appropriate kind, to the
 parsers being invoked to parse the global values. Parsers will store the
@@ -120,32 +120,31 @@ for standard options in libdhcp++. However, the formats for vendor specific
 options are dynamically configured by the server's administrator and thus can't
 be stored in libdhcp++. Such option formats are stored in the
 @ref isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
-of options which may be encapsulated by other options up to the any level of
-encapsulation but these functions are unaware of the option formats defined
+of options which may be encapsulated by other options up to any level of
+encapsulation, but these functions are unaware of the option formats defined
 in the @ref isc::dhcp::CfgMgr because they belong to a different library.
 Therefore, the generic functions @ref isc::dhcp::LibDHCP::unpackOptions4 and
-@ref isc::dhcp::LibDHCP::unpackOptions4 are only useful to parse standard
-options which definitions are provided in the libdhcp++. In order to overcome
+@ref isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
+options whose definitions are provided in the libdhcp++. In order to overcome
 this problem a callback mechanism has been implemented in @c Option and @c Pkt4
-classes. By installing a callback function on the instance of the @c Pkt4 the
+classes. By installing a callback function on an instance of @c Pkt4, the
 server may provide a custom implementation of the options parsing algorithm.
 This callback function will take precedence over the @c LibDHCP::unpackOptions4
-and @c LibDHCP::unpackOptions4 functions. With this approach, the callback is
+and @c LibDHCP::unpackOptions6 functions. With this approach, the callback is
 implemented within the context of the server and it has access to all objects
 which define its configuration (including dynamically created option
 definitions).
 
 @section dhcpv4DDNSIntegration DHCPv4 Server Support for the Dynamic DNS Updates
-T
-he DHCPv4 server supports processing of the DHCPv4 Client FQDN option (RFC4702)
-and the DHCPv4 Host Name option (RFC2132). Client may send one of these options
+The DHCPv4 server supports processing of the DHCPv4 Client FQDN option (RFC4702)
+and the DHCPv4 Host Name option (RFC2132). A client may send one of these options
 to convey its fully qualified or partial name to the server. The server may use
 this name to perform DNS updates for the client. If server receives both options
 in the same message, the DHCPv4 Client FQDN %Option is processed and the Host
 Name option is ignored. If only Host Name Option is present in the client's
 message, it is used to update DNS.
 
-Server may be configured to use a different name to perform DNS update for the
+The server may be configured to use a different name to perform DNS update for the
 client. In this case the server will return one of the DHCPv4 Client FQDN or
 Host Name %Option in its response with the name which was selected for the
 client to indicate that this name will be used to perform DNS update.
@@ -170,7 +169,7 @@ or 2 NameChangeRequests during single message processing. Server generates no
 NameChangeRequests if it is not configured to update DNS or it rejects the DNS
 update for any other reason.
 
-Server may generate 1 NameChangeRequest in a case when client acquired a new
+The server may generate one NameChangeRequest in the case when client acquires a new
 lease or it releases an existing lease. In the former case, the NameChangeRequest
 type is CHG_ADD, which indicates that the kea-dhcp-ddns module should add a new
 DNS binding for the client, and it is assumed that there is no DNS binding for
@@ -183,15 +182,15 @@ forward only update or both reverse and forward update) have been performed when
 the lease was acquired or renewed. Server checks this information to make a
 decision which mapping it is supposed to remove when lease is released.
 
-Server may generate 2 NameChangeRequests in case a client is renewing a lease and
-it already has a DNS binding for that lease. The DHCPv4 server will check if
-there is an existing lease for the client which has sent a message and if DNS
-Updates had been performed for this lease. If the notion of client's FQDN changes,
-comparing to the information stored in the lease database, the DHCPv4 has to
-remove an existing binding from the DNS and then add a new binding according to
-the new FQDN information received from the client. If the client's FQDN
-information (including the client's name and type of update performed) doesn't
-change comparing to the NameChangeRequest is not generated.
+The server may generate two NameChangeRequests in the case where client is
+renewing a lease and it already has a DNS binding for that lease. The DHCPv4
+server will check if there is an existing lease for the client which has sent a
+message and if DNS Updates had been performed for this lease. If the notion of
+client's FQDN changes, comparing to the information stored in the lease
+database, the DHCPv4 has to remove an existing binding from the DNS and then add
+a new binding according to the new FQDN information received from the client. If
+the client's FQDN information (including the client's name and type of update
+performed) doesn't change comparing to the NameChangeRequest is not generated.
 
 The DHCPv4 Client FQDN %Option comprises flags which communicate to the server
 what updates (if any) client expects the server to perform. Server may be
@@ -200,7 +199,7 @@ If the server overrides client's preference it will communicate it by sending
 the DHCPv4 Client FQDN %Option in its responses to a client, with the appropriate
 flags set.
 
-@todo Note, that current implementation doesn't allow configuration of the
+@todo Note: the current implementation doesn't allow configuration of the
 server's behaviour with respect to DNS Updates. This is planned for the future.
 The default behaviour is constituted by the set of constants defined in the
 (upper part of) dhcp4_srv.cc file. Once the configuration is implemented,
@@ -208,7 +207,7 @@ these constants will be removed.
 
 @section dhcpv4Classifier DHCPv4 Client Classification
 
-Kea DHCPv4 server currently supports simplified client classification. It is called
+The Kea DHCPv4 server currently supports simplified client classification. It is called
 "simplified", because the incoming packets are classified based on the content
 of the vendor class (60) option. More flexible classification is planned, but there
 are no specific development dates agreed.
@@ -293,11 +292,11 @@ a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.
 
 The signal handler reconfigures the server using the configuration file
-specified at the server startup. The location of this file is held in the
+specified at server startup. The location of this file is held in the
 @c Daemon class.
 
 @section dhcpv4Other Other DHCPv4 topics
 
- For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
+For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
 
 */

src/bin/dhcp4/dhcp4_hooks.dox

@@ -157,7 +157,7 @@ packet processing. Hook points that are not specific to packet processing
 
  - <b>Skip flag action</b>: If any callout installed on "lease4_renew"
    sets the skip flag, the server will not update the lease in the
-   database and continue using old values instead.
+   database and will continue using the old values instead.
 
 @subsection dhcpv4HooksLeaseRelease lease4_release
 

src/bin/dhcp6/dhcp6.dox

@@ -142,10 +142,10 @@ send them to the kea-dhcp-ddns module when server is idle waiting for DHCP messa
 
 In the simplest case, when client gets one address from the server, a DHCPv6 server
 may generate 0, 1 or 2 NameChangeRequests during single message processing.
-Server generates no NameChangeRequests if it is not configured to update DNS
+The server generates no NameChangeRequests if it is not configured to update DNS
  or it rejects the DNS update for any other reason.
 
-Server may generate 1 NameChangeRequest in a situation when a client acquires a
+The server may generate one NameChangeRequest in a situation when a client acquires a
 new lease or it releases an existing lease. In the former case, the NameChangeRequest
 type is CHG_ADD, which indicates that the kea-dhcp-ddns module should add a new DNS
 binding for the client, and it is assumed that there is no DNS binding for this
@@ -158,7 +158,7 @@ both reverse and forward update) have been performed when the lease was acquired
 Server checks this information to make a decision which mapping it is supposed to
 remove when a lease is released.
 
-Server may generate 2 NameChangeRequests in case the client is renewing a lease and
+The server may generate two NameChangeRequests in case the client is renewing a lease and
 it already has a DNS binding for that lease. Note, that renewal may be triggered
 as a result of sending a RENEW message as well as the REQUEST message. In both cases
 DHCPv6 server will check if there is an existing lease for the client which has sent
@@ -202,7 +202,7 @@ encapsulation but these functions are unaware of the option formats defined
 in the @ref isc::dhcp::CfgMgr because they belong to a different library.
 Therefore, the generic functions @ref isc::dhcp::LibDHCP::unpackOptions4 and
 @ref isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
-options which definitions are provided in the libdhcp++. In order to overcome
+options whose definitions are provided in the libdhcp++. In order to overcome
 this problem a callback mechanism has been implemented in @c Option and @c Pkt6
 classes. By installing a callback function on the instance of the @c Pkt6 the
 server may provide a custom implementation of the options parsing algorithm.
@@ -214,7 +214,7 @@ definitions).
 
 @section dhcpv6Classifier DHCPv6 Client Classification
 
-Kea DHCPv6 server currently supports simplified client classification. It is called
+The Kea DHCPv6 server currently supports simplified client classification. It is called
 "simplified", because the incoming packets are classified based on the content
 of the vendor class (16) option. More flexible classification is planned, but there
 are no specific development dates agreed.
@@ -247,13 +247,14 @@ limited.
 
  @section dhcpv6ConfigBackend Configuration backend for DHCPv6
 
-There are many theoretical ways in which server configuration can be stored.
+There are many theoretical ways in which the server configuration can be stored.
 The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
 becoming more and more popular among various projects. There are unofficial patches for
 ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
 cases it would be convenient to keep configuration in XML files.
 
-Kea 0.9 has introduced configuration backends that are switchable during compilation phase. Currently the only choice is JSON.
+Kea 0.9 has introduced configuration backends that are switchable during the
+compilation phase. Currently the only choice is JSON.
 
 JSON is a new configuration backend that causes Kea to read JSON configuration file from
 disk. It does not require any framework and thus is considered more lightweight. It will
@@ -296,11 +297,11 @@ a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.
 
 The signal handler reconfigures the server using the configuration file
-specified at the server startup. The location of this file is held in the
+specified at server startup. The location of this file is held in the
 @c Daemon class.
 
- @section dhcpv6Other Other DHCPv6 topics
+@section dhcpv6Other Other DHCPv6 topics
 
- For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
+For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
 
  */

src/lib/dhcp/libdhcp++.dox

@@ -36,10 +36,10 @@ smart pointers using the \c boost::shared_ptr type. There are no const
 versions of packet types defined, as we assume that hooks can modify any
 aspect of the packet at almost any stage of processing.
 
-Both packet types use collection of \ref isc::dhcp::Option objects to
+Both packet types use a collection of \ref isc::dhcp::Option objects to
 represent DHCPv4 and DHCPv6 options. The base class @c Option can be used to
 represent generic option that contains collection of
-bytes. Depending on whether the option is instantiated as DHCPv4 or DHCPv6
+bytes. Depending on whether the option is instantiated as a DHCPv4 or DHCPv6
 option, it will adjust its header (DHCPv4 options use 1 octet for
 type and 1 octet for length, while DHCPv6 options use 2 bytes for
 each).
@@ -50,13 +50,13 @@ specific formats:
 - isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses;
 - isc::dhcp::Option4ClientFqdn -- DHCPv4 Client FQDN option;
 - isc::dhcp::Option6ClientFqdn -- DHCPv6 Client FQDN option;
-- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR option (an option that
+- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents the IAADDR option (an option that
                               contains IPv6 address with extra parameters);
-- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents IAPREFIX option (an option
+- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents the IAPREFIX option (an option
                                 that contains IPv6 prefix in prefix delegation);
 - isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions.
 - isc::dhcp::Option6StatusCode -- DHCPv6 option, carries a status code to the client;
-- isc::dhcp::OptionCustom -- Represents option having many different formats, where
+- isc::dhcp::OptionCustom -- Represents an option having many different formats, where
                              data fields can be accessed in a convenient way;
 - isc::dhcp::OptionInt -- DHCPv4 or DHCPv6 option, carries a single numeric value;
 - isc::dhcp::OptionString -- DHCPv4 or DHCPv6 option, carries a text value;
@@ -93,7 +93,7 @@ that interface-id in its copy, when sending data back to the client.
 This will be used by the relay to choose proper interface when forwarding
 response towards the client.
 
-Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo.
+The Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo.
 This is a simple structure that represents the information in each RELAY_FORW
 or RELAY_REPL message. It is important to understand the order in which
 the data appear here. Consider the following network:
@@ -125,10 +125,10 @@ network operations. In particlar, it provides information about existing
 network interfaces See @ref isc::dhcp::Iface class and
 @ref isc::dhcp::IfaceMgr::detectIfaces() and @ref isc::dhcp::IfaceMgr::getIface().
 
-Generic parts of the code are @ref isc::dhcp::IfaceMgr class in
+Generic parts of the code are contained in the @ref isc::dhcp::IfaceMgr class in
 src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate
-files, e.g. iface_mgr_linux.cc, iface_mgr_bsd. Such separation should be
-maintained when additional code will be developed.
+files, e.g. iface_mgr_linux.cc, iface_mgr_bsd. The separation should be
+maintained when developing additional code.
 
 Other useful methods are dedicated to transmission
 (\ref isc::dhcp::IfaceMgr::send(), 2 overloads) and reception

src/lib/dhcpsrv/database_backends.dox

@@ -205,7 +205,7 @@ host    all             all             ::1/128                 password
   Please consult your PostgreSQL user manual before applying those changes as
   those changes may expose your other databases that you run on the same system.
   In general case, it is a poor idea to run anything of value on a system
-  that runs tests. Use caution!§
+  that runs tests. Use caution!
 
   The unit tests are run automatically when "make check" is executed (providing
   that Kea has been build with the \--with-dhcp-pgsql switch (see the installation

src/lib/dhcpsrv/libdhcpsrv.dox

@@ -15,36 +15,35 @@
 /**
  @page libdhcpsrv libdhcpsrv - Server DHCP library
 
-This library contains code used for DHCPv4 and DHCPv6 servers' operations,
-including "Lease Manager" that manages information about leases,
-"Configuration Manager" that stores servers' configuration etc.
-The code here is server specific. For generic (useful by server,
+This library contains code used for the DHCPv4 and DHCPv6 servers' operations,
+including the "Lease Manager" that manages information about leases and the
+"Configuration Manager" that stores the servers' configuration etc.
+The code here is server specific. For generic (useful to the server,
 client, relay and other tools like perfdhcp) code, please see
 \ref libdhcp.
 
-This library contains several crucial elements for the DHCP server operation:
+This library contains several crucial elements for the operation of the DHCP server:
 
-- isc::dhcp::LeaseMgr - lease manager is a name for database backend that stores
+- isc::dhcp::LeaseMgr - lease manager is the name for the database backend that stores
   leases.
 - isc::dhcp::CfgMgr - configuration manager that holds DHCP specific
   configuration information (subnets, pools, options, timer values etc.) in
   easy to use format.
-- isc::dhcp::AllocEngine - allocation engine that handles new requestes and allocates new
+- isc::dhcp::AllocEngine - allocation engine that handles new requests and allocates new
   leases.
-- isc::dhcp::HostMgr - manager for static reservations, a.k.a. as host
-  reservations.
-- isc::dhcp::D2ClientMgr - D2 client manager which is responsible for
+- isc::dhcp::HostMgr - manager for static reservations (a.k.a. host reservations).
+- isc::dhcp::D2ClientMgr - DHCP-DDNS (D2) client manager which is responsible for
   the communication between the DHCP server and the D2 component.
 
 @section leasemgr Lease Manager
 
 LeaseMgr provides a common, unified abstract API for all database backends. All
 backends are derived from the base class isc::dhcp::LeaseMgr. Currently Kea
-supports three backends implemented in the following classes:
+supports three backends, implemented in the following classes:
 
-- isc::dhcp::Memfile_LeaseMgr - stores leases in the CSV file,
-- isc::dhcp::MySqlLeaseMgr - stores leases in the MySQL database
-- isc::dhcp::PgSqlLeaseMgr - stores leases in the PostgreSQL database
+- isc::dhcp::Memfile_LeaseMgr - stores leases in a CSV file,
+- isc::dhcp::MySqlLeaseMgr - stores leases in a MySQL database
+- isc::dhcp::PgSqlLeaseMgr - stores leases in a PostgreSQL database
 
 @section cfgmgr Configuration Manager