[master] Merge branch 'trac3484'

doc/Doxyfile

@@ -45,7 +45,7 @@ PROJECT_BRIEF          =
 # exceed 55 pixels and the maximum width should not exceed 200 pixels.
 # Doxygen will copy the logo to the output directory.
 
-PROJECT_LOGO           =
+PROJECT_LOGO           = images/isc-logo.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
 # base path where the generated documentation will be put.
@@ -659,6 +659,7 @@ INPUT                  = ../src/bin/d2 \
                          ../src/lib/dhcp \
                          ../src/lib/dhcp_ddns \
                          ../src/lib/dhcpsrv \
+                         ../src/lib/dhcpsrv/parsers \
                          ../src/lib/dns \
                          ../src/lib/exceptions \
                          ../src/lib/hooks \

doc/devel/contribute.dox

@@ -58,7 +58,7 @@ a regular x86 architecture machine to write your patch, but the software
 is expected to run on many other architectures. You may take a look at
 system specific build notes (http://kea.isc.org/wiki/SystemSpecificNotes).
 For a complete list of systems we build on, you may take a look at the
-following build farm report: http://git.kea.isc.org/~tester/builder/KEA-builder-new.html .
+following build farm report: https://jenkins.isc.org/view/Kea_BuildFarm/ .
 
 Does your patch conform to Kea coding guidelines
 (http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
@@ -78,6 +78,30 @@ 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 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.
 
 If you happen to add new files or have modified any \c Makefile.am
@@ -94,10 +118,10 @@ checks on logger parameters. Use \c --enable-debug to enable various
 additional consistency checks that reduce performance but help during
 development. If you happen to modify anything in the
 documentation, use \c --enable-generate-docs. If you are modifying DHCP
-code, you are likely to be interested in enabling a database backend for
-DHCP. Note that if the backend is not enabled, the database-specific unit-tests
-are skipped. To enable the MySQL backend, use the switch
-\c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
+code, you are likely to be interested in enabling a non-default database
+backends for DHCP. Note that if the backend is not enabled,
+the database-specific unit-tests are skipped. To enable the MySQL backend,
+use the switch \c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
 A complete list of all switches can be obtained with the command:
 
 @code

doc/devel/mainpage.dox

@@ -15,12 +15,12 @@
 /**
  * @mainpage Kea Developer's Guide
  *
- * Welcome to Kea Developer's Guide. This documentation is addressed
- * at existing and prospecting developers and programmers and provides
- * information needed to both extend and maintain Kea.
- *
+ * Welcome to Kea Developer's Guide. This documentation is addressed at
+ * either existing or prospective Kea developers and contributors, and
+ * provides information needed to extend and maintain Kea.
+
  * If you wish to write "hook" code - code that is loaded by Kea at
- * run-time and modifies its behavior you should read the section
+ * run-time and modifies its behavior,  you should read the section
  * @ref hooksdgDevelopersGuide.
  *
  * Kea maintenance information is divided into a number of sections
@@ -30,8 +30,11 @@
  *
  * If you are a user or system administrator, rather than software engineer,
  * you should read the
- * <a href="http://kea.isc.org/docs/bind10-guide.html">Kea
- * Administrator Reference Manual</a> instead.
+ * <a href="http://kea.isc.org/docs/kea-guide.html">Kea
+ * 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.
  *
  * Regardless of your field of expertise, you are encouraged to visit the
  * <a href="http://kea.isc.org/">Kea webpage (http://kea.isc.org)</a>
@@ -117,10 +120,5 @@
  * - @subpage SocketSessionUtility
  * - <a href="./doxygen-error.log">Documentation warnings and errors</a>
  *
- * @image html isc-logo.png
- */
-/*
- * @todo: Move the logo to the right (and possibly up). Not sure what
- * is the best way to do it in Doxygen, without using CSS hacks.
  */
 

src/bin/dhcp4/dhcp4.dox

@@ -15,46 +15,136 @@
 /**
  @page dhcp4 DHCPv4 Server Component
 
-Kea offers DHCPv4 server implementation. It is implemented as
-kea-dhcp4 component.  Its primary code is located in
-isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
-especially isc::dhcp::Pkt4, isc::dhcp::Option and
-isc::dhcp::IfaceMgr classes. Currently this code offers skeleton
-functionality, i.e. it is able to receive and process incoming
-requests and transmit responses. However, it does not have database
-management, so it returns only one, hardcoded lease to whoever asks
-for it.
-
-DHCPv4 server component does not support direct traffic (relayed
-only), as support for transmission to hosts without IPv4 address
-assigned is not implemented in IfaceMgr yet.
+Kea includes the "kea-dhcp4" component, which is the DHCPv4 server
+implementation. This component is built around the
+@ref isc::dhcp::Dhcpv4Srv class which controls all major operations
+performed by the server such as: DHCP messages processing, callouts
+execution for many hook points, FQDN processing and interactions with the
+"kea-dhcp-ddns" component, lease allocation, system signals handling etc.
+
+The "kea-dhcp4" component requires linking with many different libraries
+to obtain access to common functions like: interfaces and sockets
+management, configuration parsing, leases management and allocation,
+hooks infrastructure, statistics management etc.
+
+The following sections walk through some of the details of the "kea-dhcp4"
+component implementation.
 
 @section dhcpv4ConfigParser Configuration Parser in DHCPv4
 
-This parser follows exactly the same logic as its DHCPv6 counterpart.
-See \ref dhcpv6ConfigParser.
+The common configuration parsers for the DHCP servers are located in the
+src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv4 component
+are located in the src/bin/dhcp4/json_config_parser.cc. These parsers derive
+from the common configuration parsers and customize their behavior. For
+example: the @c Subnet4ConfigParser is used to parse parameters
+describing a single subnet. It derives from the @c
+isc::dhcp::SubnetConfigParser, which implements the common base for both
+DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet4ConfigParser
+implements the @c initSubnet abstract method, which creates an instance of
+the DHCPv4 subnet. This method is invoked by the parent class.
+
+Some parsers for the DHCPv4 server derive from the isc::dhcp::DhcpConfigParser
+class directly. This is an abstract class, defining a basic interface for
+all configuration parsers. All DHCPv4 parsers deriving from this class
+directly have their entire implementation in the
+src/bin/dhcp4/json_config_parser.cc.
 
 @section dhcpv4ConfigInherit DHCPv4 configuration inheritance
 
-Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
-counterpart. See \ref dhcpv6ConfigInherit.
+One notable useful feature of DHCP configuration is its parameter inheritance.
+For example, "renew-timer" value may be specified at a global scope and it then
+applies to all subnets. However, some subnets may have it overwritten with subnet
+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 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
+parsed values into these storages. Once the global parameters are stored in the
+global context, the parsers for the nested configuration parameters are invoked.
+These parsers check the presence of the parameters overriding the values of
+the global parameters. If a value is not present, the values from the global
+context is used.
+
+A good example of inheritance is the implementation of the @ref
+isc::dhcp::SubnetConfigParser. The @c getParam method is used throughout the
+class to obtain values of the parameters defining a subnet. It first checks
+if the specific value is present in the local values storage. If it is not
+present, it uses the value from the global context.
+
+ @code
+ isc::dhcp::Triplet<uint32_t>
+ SubnetConfigParser::getParam(const std::string& name) {
+     uint32_t value = 0;
+     try {
+         // look for local value
+          value = uint32_values_->getParam(name);
+     } catch (const DhcpConfigError &) {
+         try {
+             // no local, use global value
+             value = global_context_->uint32_values_->getParam(name);
+         } catch (const DhcpConfigError &) {
+             isc_throw(DhcpConfigError, "Mandatory parameter " << name
+                       << " missing (no global default and no subnet-"
+                       << "specific value)");
+         }
+     }
+
+     return (Triplet<uint32_t>(value));
+}
+@endcode
+
+Note that if the value is neither present in the local storage nor in the global
+context an error is signalled.
+
+Parameter inheritance is done once, during the reconfiguration phase.
+Reconfigurations are rare, so extra logic here is not a problem. On the other
+hand, values of those parameters may be used thousands times per second, so
+access to these parameters must be as efficient as possible. In fact,
+currently the code has to only call @c Subnet4::getT1(), regardless if the
+"renew-timer" has been specified as a global or subnet specific value.
+
+Debugging a configuration parser may be confusing. Therefore there is a special
+class called DebugParser. It does not configure anything, but just
+accepts any parameter of any type. If requested to commit configuration, it will
+print out received parameter name and its value. This class is not currently used,
+but it is convenient to have it every time a new parameter is added to the DHCP
+configuration. For that purpose it should be left in the code.
 
 @section dhcpv4OptionsParse Custom functions to parse message options
 
-The DHCPv4 server uses the same logic to supply custom callback function to
-parse message option as DHCPv6 server implementation. See \ref dhcpv6OptionsParse.
+The DHCPv4 server implementation provides a generic support to define option
+formats and set option values. A number of options formats have been defined
+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 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::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 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::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.
@@ -79,8 +169,8 @@ 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
-lease or it releases an existing lease. In the former case, the NameChangeRequest
+The server may generate one NameChangeRequest in the case where a client acquires a new
+lease or it releases an existing one. 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 client already. In the latter case, the NameChangeRequest type is CHG_REMOVE
@@ -92,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
@@ -109,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,
@@ -117,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.
@@ -201,16 +291,12 @@ through the main loop. This method fetches the last received signal and calls
 a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.
 
-In order for the signal handler to know the location of the configuration file
-(specified at process startup), the location of this file needs to be stored
-in a static variable so as it may be directly accessed by the signal handler.
-This static variable is stored in the @c dhcp::Daemon class and all Kea processes
-can use it (all processes derive from this class). The configuration file
-location is initialized when the @c Daemon::init method is called. Therefore,
-derived classes should call it in their implementations of the @c init method.
+The signal handler reconfigures the server using the configuration file
+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

@@ -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
@@ -22,7 +22,7 @@
  the @ref hooksdgDevelopersGuide.  Information for Kea maintainers can be
  found in the @ref hooksComponentDeveloperGuide.
 
- This manual is more specialised and is aimed at developers of hook
+ This manual is more specialized and is aimed at developers of hook
  code for the DHCPv4 server. It describes each hook point, what the callouts
  attached to the hook are able to do, and the arguments passed to the
  callouts.  Each entry in this manual has the following information:
@@ -54,23 +54,25 @@ packet processing. Hook points that are not specific to packet processing
  - @b Arguments:
    - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed when an incoming DHCPv4
-   buffer is received, before its content is parsed. The sole argument
-   - query4 - contains a pointer to an isc::dhcp::Pkt4 object that
-   contains raw information regarding incoming packet, including its
-   source and destination addresses, interface over which it was
-   received, and a raw buffer stored in data_ field. None of the
-   packet fields (op_, hlen_, chaddr_, etc.) are set yet. Callouts
-   installed on this hook point can modify the incoming buffer. The
-   server will parse the buffer afterwards.
+ - @b Description: this callout is executed when the server has received a
+   buffer containing a DHCPv4 message, but the message hasn't yet been parsed.
+   The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4
+   object, which contains the source and destination address of the
+   received packet, the interface over which the packet has been received, and
+   a raw buffer, stored in the data_ field, containing the DHCPv4 message
+   in the wire format. None of the packet fields (op_, hlen_, chaddr_, etc.)
+   are set yet. Callouts installed on this hook point can modify the data
+    in the received buffer. The server will parse the buffer afterwards.
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
-   skip the buffer parsing. In such case there is an expectation that
-   the callout will parse the buffer and create option objects (see
-   isc::dhcp::Pkt4::addOption()). Otherwise the server will find out
-   that some mandatory options are missing (e.g. DHCP Message Type) and
-   will drop the packet. If you want to have the capability to drop
-   a message, it is better to use skip flag in pkt4_receive callout.
+   skip the buffer parsing. In this case there is an expectation that
+   the callout will parse the options carried in the buffer, create
+   @c isc::dhcp::Option objects (or derived) and add them to the "query4"
+   object using the @c isc::dhcp::Pkt4::addOption.
+   Otherwise the server will find out that some mandatory options are
+   missing (e.g. DHCP Message Type) and will drop the message. If you
+   want to have the capability to drop a message, it is better to use
+   the skip flag in the "pkt4_receive" callout.
 
  @subsection dhcpv4HooksPkt4Receive pkt4_receive
 
@@ -79,15 +81,14 @@ packet processing. Hook points that are not specific to packet processing
 
  - @b Description: this callout is executed when an incoming DHCPv4
    packet is received and its content has been parsed. The sole
-   argument - query4 - contains a pointer to an isc::dhcp::Pkt4 object
+   argument "query4" contains a pointer to an isc::dhcp::Pkt4 object
    that contains all information regarding incoming packet, including
    its source and destination addresses, interface over which it was
-   received, a list of all options present within and relay
+   received, a list of all options present within and the relay
    information.  All fields of the Pkt4 object can be modified at this
-   time, except data_. (By the time this hook is reached, the contents
-   of the data_ field has been already parsed and stored in other
-   fields. Therefore, the modification in the data_ field has no
-   effect.)
+   time. By the time this hook is reached, the contents of the data_
+   field has been already parsed and stored in other fields. Therefore,
+   the modification in the data_ field has no effect.
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
    drop the packet and start processing the next one.  The reason for the drop
@@ -98,19 +99,19 @@ packet processing. Hook points that are not specific to packet processing
  - @b Arguments:
    - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
    - name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in/out</b>
-   - name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, direction: <b>in</b>
+   - name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *,
+     direction: <b>in</b>
 
  - @b Description: this callout is executed when a subnet is being
    selected for the incoming packet. All parameters and addresses
    will be assigned from that subnet. A callout can select a
-   different subnet if it wishes so, the list of all subnets currently
-   configured being provided as 'subnet4collection'. The list itself must
+   different subnet if it wishes so. The list of all subnets currently
+   configured are provided as "subnet4collection". The list itself must
    not be modified.
 
- - <b>Skip flag action</b>: If any callout installed on 'subnet4_select'
+ - <b>Skip flag action</b>: If any callout, installed on "subnet4_select",
    sets the skip flag, the server will not select any subnet. Packet processing
-   will continue, but will be severely limited (i.e. only global options
-   will be assigned).
+   will continue, but will be severely limited.
 
 @subsection dhcpv4HooksLeaseSelect lease4_select
 
@@ -120,22 +121,24 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
 
  - @b Description: this callout is executed after the server engine
-   has selected a lease for client's request but before the lease has
+   has selected a lease for the client's request, but before the lease has
    been inserted into the database. Any modifications made to the
-   isc::dhcp::Lease4 object will be stored in the lease's record in
-   the database. The callout should sanity check all modifications as
-   the server will use that data as is with no further checking.\n\n
-   The server processes lease requests for DISCOVER and REQUEST in a
-   very similar way. The only major difference is that for DISCOVER
-   the lease is just selected, but not inserted into the database.  It
-   is possible to distinguish between DISCOVER and REQUEST by checking
-   value of the fake_allocation flag: a value of true indicates that the
-   lease won't be inserted into the database (DISCOVER), a value of
-   false indicates that it will (REQUEST).
-
- - <b>Skip flag action</b>: If any callout installed on 'lease4_select'
-   sets the skip flag, the server will not assign any lease. Packet
-   processing will continue, but client will not get an address.
+   "lease4" object will affect the lease's record in the database.
+   The callout should sanity check all modifications as the server will
+   use that data as is, with no further checking.\n\n
+   The server processes lease requests for DHCPDISCOVER and DHCPREQUEST in a
+   very similar way. The only major difference is that for DHCPDISCOVER
+   the lease is only selected, but not inserted into the database. The callouts
+   may distinguish between DHCPDISCOVER and DHCPREQUEST by checking the
+   value of the "fake_allocation" flag: a value of true indicates that the
+   lease won't be inserted into the database (DHCPDISCOVER case), a value of
+   false indicates that it will (DHCPREQUEST case).
+
+ - <b>Skip flag action</b>: If any callout installed on "lease4_select"
+   sets the skip flag, the server will not assign any lease and the callouts
+   become responsible for the lease assignment. If the callouts fail to provide
+   a lease, the packet processing will continue, but client will not get
+   an address.
 
 @subsection dhcpv4HooksLeaseRenew lease4_renew
 
@@ -146,15 +149,15 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
 
  - @b Description: this callout is executed when the server engine
-   is about to renew a lease, as a result of receiving REQUEST/Renewing
-   packet. The lease4 argument points to Lease4 object that contains
-   the updated values. Callout can modify those values. Care should be taken
-   as the server will attempt to update the lease in the database without
-   any additional checks.
+   is about to renew a lease, as a result of receiving DHCPREQUEST/Renewing
+   packet. The "lease4" argument points to @c isc::dhcp::Lease4 object that
+   contains the updated values. Callout can modify those values. Care should
+   be taken as the server will attempt to update the lease in the database
+   without any additional checks.
 
- - <b>Skip flag action</b>: If any callout installed on 'lease4_renew'
-   sets the skip flag, the server will not update the lease and will
-   use old values instead.
+ - <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 will continue using the old values instead.
 
 @subsection dhcpv4HooksLeaseRelease lease4_release
 
@@ -163,11 +166,11 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in</b>
 
  - @b Description: this callout is executed when the server engine
-   is about to release a lease, as a result of receiving RELEASE packet.
-   The lease4 argument points to Lease4 object that contains the lease to
+   is about to release a lease, as a result of receiving DHCPRELEASE packet.
+   The "lease4" argument points to @c Lease4 object that contains the lease to
    be released. It doesn't make sense to modify it at this time.
 
- - <b>Skip flag action</b>: If any callout installed on 'lease4_release'
+ - <b>Skip flag action</b>: If any callout installed on "lease4_release"
    sets the skip flag, the server will not delete the lease. It will be
    kept in the database and will go through the regular expiration/reuse
    process.
@@ -178,17 +181,17 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
 
  - @b Description: this callout is executed when server's response
-   is about to be sent back to the client. The sole argument - response4 -
-   contains a pointer to an isc::dhcp::Pkt4 object that contains the
+   is about to be sent back to the client. The sole argument "response4"
+   contains a pointer to an isc::dhcp::Pkt4 object carrying the
    packet, with source and destination addresses set, interface over which
    it will be sent, and a list of all options and relay information.  All fields
-   of the Pkt4 object can be modified at this time, except buffer_out_.
+   of the @c Pkt4 object can be modified at this time, except @c buffer_out_.
    (This is scratch space used for constructing the packet after all
    pkt4_send callouts are complete, so any changes to that field will
    be overwritten.)
 
  - <b>Skip flag action</b>: if any callout sets the skip flag, the server
-   will not construct raw buffer. The expectation is that if the callout
+   will not construct the raw buffer. The expectation is that if the callout
    set skip flag, it is responsible for constructing raw form on its own.
    Otherwise the output packet will be sent with zero length.
 
@@ -198,17 +201,19 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
 
  - @b Description: this callout is executed when server's response
-   is about to be sent back to the client. The sole argument - response4 -
-   contains a pointer to an isc::dhcp::Pkt4 object that contains the
+   is about to be sent back to the client. The sole argument "response4"
+   contains a pointer to an @c isc::dhcp::Pkt4 object that contains the
    packet, with source and destination addresses set, interface over which
    it will be sent, and a list of all options and relay information. The raw
-   on-wire form is already prepared in buffer_out_ (see isc::dhcp::Pkt4::getBuffer())
-   It doesn't make any sense to modify packet fields or options content
-   at this time, because they were already used to construct on-wire buffer.
+   on-wire form is already prepared in @c buffer_out_ (see
+   @c isc::dhcp::Pkt4::getBuffer())
+   Callouts should not modify the packet fields or options contents at this
+   time, because they were already used to construct on-wire buffer. Their
+   modification would have no effect.
 
  - <b>Skip flag action</b>: if any callout sets the skip flag, the server
    will drop this response packet. However, the original request packet
-   from a client was processed, so server's state was most likely changed
+   from a client was processed, so server's state most likely has changed
    (e.g. lease was allocated). Setting this flag merely stops the change
    being communicated to the client.
 

src/bin/dhcp4/dhcp4_srv.h

@@ -156,9 +156,6 @@ typedef boost::shared_ptr<Dhcpv4Exchange> Dhcpv4ExchangePtr;
 /// This class does not support any controlling mechanisms directly.
 /// See the derived \ref ControlledDhcpv4Srv class for support for
 /// command and configuration updates over msgq.
-///
-/// For detailed explanation or relations between main(), ControlledDhcpv4Srv,
-/// Dhcpv4Srv and other classes, see \ref dhcpv4Session.
 class Dhcpv4Srv : public Daemon {
 
 public:

src/bin/dhcp4/main.cc

@@ -33,9 +33,6 @@ using namespace std;
 /// instantiates ControlledDhcpv4Srv class that is responsible for establishing
 /// connection with msgq (receiving commands and configuration) and also
 /// creating Dhcpv4 server object as well.
-///
-/// For detailed explanation or relations between main(), ControlledDhcpv4Srv,
-/// Dhcpv4Srv and other classes, see \ref dhcpv4Session.
 
 namespace {
 

src/bin/dhcp6/dhcp6.dox

@@ -15,62 +15,102 @@
 /**
  @page dhcp6 DHCPv6 Server Component
 
- Kea offers DHCPv6 server implementation. It is implemented as
- kea-dhcp6 component. Its primary code is located in
- isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively,
- especially lib::dhcp::Pkt6, isc::dhcp::Option and
- isc::dhcp::IfaceMgr classes. Currently this code offers skeleton
- functionality, i.e. it is able to receive and process incoming
- requests and transmit responses. However, it does not have database
- management, so it returns only one, hardcoded lease to whoever asks
- for it.
-
- DHCPv6 server component does not support relayed traffic yet, as
- support for relay decapsulation is not implemented yet.
-
- @section dhcpv6ConfigParser Configuration Parser in DHCPv6
-
- \note With the implementation of the Kea ticket #3534 we're moving away from
- the concept of commit being called for individual parsers. When this ticket
- and a couple of followup tickets are implemented, the commit will be a
- single operation executed for the whole configuration received from many
- parsers.
-
- All parsers are defined in src/bin/dhcp6/config_parser.cc file. Some of them
- are generic (e.g. Uint32Parser that is able to handle any
- unsigned 32 bit integer), but some are very specialized (e.g.
- Subnets6ListConfigParser parses definitions of Subnet6 lists). In some cases,
- e.g. subnet6 definitions, the configuration entry is not a simple value, but
- a map or a list itself. In such case, the parser iterates over all elements
- and creates parsers for a given scope. This process may be repeated (sort of)
- recursively.
-
- @section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
-
- One notable useful feature of DHCP configuration is its parameter inheritance.
- For example, renew-timer value may be specified at a global scope and it then
- applies to all subnets. However, some subnets may have it overwritten with more
- specific values that takes precedence over global values that are considered
- defaults. Some parsers (e.g. Uint32Parser and StringParser) implement that
- inheritance. By default, they store values in global uint32_defaults and
- string_defaults storages. However, it is possible to instruct them to store
- parsed values in more specific storages. That capability is used, e.g. in
- Subnet6ConfigParser that has its own storage that is unique for each subnet.
- Finally, during commit phase (commit() method), appropriate parsers can use
- apply parameter inheritance.
-
- Debugging configuration parser may be confusing. Therefore there is a special
- class called DebugParser. It does not configure anything, but just
- accepts any parameter of any type. If requested to commit configuration, it will
- print out received parameter name and its value. This class is not currently used,
- but it is convenient to have it every time a new parameter is added to DHCP
- configuration. For that purpose it should be left in the code.
-
- Parameter inheritance is done during reconfiguration phase, as reconfigurations
- are rare, so extra logic here is not a problem. On the other hand, values of
- those parameters may be used thousands times per second, so its use must be as
- simple as possible. In fact, currently the code has to call Subnet6->getT1() and
- do not implement any fancy inheritance logic.
+Kea includes the "kea-dhcp6" component, which is the DHCPv6 server
+implementation. This component is built around the
+@ref isc::dhcp::Dhcpv6Srv class which controls all major operations
+performed by the server such as: DHCP messages processing, callouts
+execution for many hook points, FQDN processing and interactions with the
+"kea-dhcp-ddns" component, lease allocation, system signals handling etc.
+
+The "kea-dhcp6" component requires linking with many different libraries
+to obtain access to common functions like: interfaces and sockets
+management, configuration parsing, leases management and allocation,
+hooks infrastructure, statistics management etc.
+
+The following sections walk through some of the details of the "kea-dhcp6"
+component implementation.
+
+@section dhcpv6ConfigParser Configuration Parsers in DHCPv6
+
+The common configuration parsers for the DHCP servers are located in the
+src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv6 component
+are located in the src/bin/dhcp6/json_config_parser.cc. These parsers derive
+from the common configuration parsers and customize their behavior. For
+example: the @c Subnet6ConfigParser is used to parse parameters
+describing a single subnet. It derives from the @c
+isc::dhcp::SubnetConfigParser, which implements the common base for both
+DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet6ConfigParser
+implements the @c initSubnet abstract method, which creates an instance of
+the DHCPv6 subnet. This method is invoked by the parent class.
+
+Some parsers for the DHCPv6 server derive from the isc::dhcp::DhcpConfigParser
+class directly. This is an abstract class, defining a basic interface for
+all configuration parsers. All DHCPv6 parsers deriving from this class
+directly have their entire implementation in the
+src/bin/dhcp6/json_config_parser.cc.
+
+@section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
+
+One notable useful feature of DHCP configuration is its parameter inheritance.
+For example, the "renew-timer" value may be specified at a global scope and it then
+applies to all subnets. However, some subnets may have it overwritten with subnet
+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,
+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
+parsed values into these storages. Once the global parameters are stored in the
+global context, the parsers for the nested configuration parameters are invoked.
+These parsers check the presence of the parameters overriding the values of
+the global parameters. If a value is not present, the value from the global
+context is used.
+
+A good example of inheritance is the implementation of the @ref
+isc::dhcp::SubnetConfigParser. The @c getParam method is used throughout the
+class to obtain values of the parameters defining a subnet. It first checks
+if the specific value is present in the local values storage. If it is not
+present, it uses the value from the global context.
+
+@code
+isc::dhcp::Triplet<uint32_t>
+SubnetConfigParser::getParam(const std::string& name) {
+    uint32_t value = 0;
+    try {
+        // look for local value
+         value = uint32_values_->getParam(name);
+    } catch (const DhcpConfigError &) {
+        try {
+            // no local, use global value
+            value = global_context_->uint32_values_->getParam(name);
+        } catch (const DhcpConfigError &) {
+            isc_throw(DhcpConfigError, "Mandatory parameter " << name
+                      << " missing (no global default and no subnet-"
+                      << "specific value)");
+        }
+    }
+
+    return (Triplet<uint32_t>(value));
+}
+@endcode
+
+Note that if the value is neither present in the local storage nor in the global
+context, an error is signalled.
+
+Parameter inheritance is done once, during the reconfiguration phase.
+Reconfigurations are rare, so extra logic here is not a problem. On the other
+hand, values of those parameters may be used thousands times per second, so
+access to these parameters must be as efficient as possible. In fact,
+currently the code has to only call @c Subnet6::getT1(), regardless if the
+"renew-timer" has been specified as a global or subnet specific value.
+
+Debugging a configuration parser may be confusing. Therefore there is a special
+class called DebugParser. It does not configure anything, but just
+accepts any parameter of any type. If requested to commit a configuration, it will
+print out received parameter name and its value. This class is not currently used,
+but it is convenient to have it every time a new parameter is added to DHCP
+configuration. For that purpose it should be left in the code.
 
 @section dhcpv6DDNSIntegration DHCPv6 Server Support for the Dynamic DNS Updates
 
@@ -102,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
@@ -118,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
@@ -156,13 +196,13 @@ formats and set option values. A number of options formats have been defined
 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
-@c isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
+@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
-in the @c isc::dhcp::CfgMgr because they belong to a different library.
-Therefore, the generic functions @c isc::dhcp::LibDHCP::unpackOptions4 and
-@c isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
-options which definitions are provided in the libdhcp++. In order to overcome
+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 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.
@@ -174,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.
@@ -207,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
@@ -255,16 +296,12 @@ through the main loop. This method fetches the last received signal and calls
 a handler function defined in the kea_controller.cc. The handler function
 calls a static function @c configure defined in the kea_controller.cc.
 
-In order for the signal handler to know the location of the configuration file
-(specified at process startup), the location of this file needs to be stored
-in a static variable so as it may be directly accessed by the signal handler.
-This static variable is stored in the @c dhcp::Daemon class and all Kea processes
-can use it (all processes derive from this class). The configuration file
-location is initialized when the @c Daemon::init method is called. Therefore,
-derived classes should call it in their implementations of the @c init method.
+The signal handler reconfigures the server using the configuration file
+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/bin/dhcp6/dhcp6_hooks.dox

@@ -55,25 +55,25 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
  - @b Description: This callout is executed when an incoming DHCPv6
-   packet is received and the data stored in a buffer. The sole argument -
-   query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
+   packet is received and the data stored in a buffer. The sole argument
+   "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
    the received information stored in the data_ field. Basic information
    like protocol, source/destination addresses and ports are set, but
    the contents of the buffer have not yet been parsed.  That means that
-   the options_ field (that will eventually contain a list of objects
+   the @c options_ field (that will eventually contain a list of objects
    representing the received options) is empty, so none of the methods
    that operate on it (e.g., getOption()) will work. The primary purpose
    of this early call is to offer the ability to modify incoming packets
    in their raw form. Unless you need to access to the raw data, it is
-   usually better to install your callout on the pkt6_receive hook point.
+   usually better to install your callout on the "pkt6_receive" hook point.
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the
-   server will assume that the callout parsed the buffer and added then
-   necessary option objects to the options_ field; the server will not
+   server will assume that the callout parsed the buffer and added the
+   necessary option objects to the @c options_ field; the server will not
    do any parsing. If the callout sets the skip flag but does not parse
    the buffer, the server will most probably drop the packet due to
    the absence of mandatory options. If you want to drop the packet,
-   see the description of the skip flag in the pkt6_receive hook point.
+   see the description of the skip flag in the "pkt6_receive" hook point.
 
  @subsection dhcpv6HooksPkt6Receive pkt6_receive
 
@@ -81,16 +81,16 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
  - @b Description: This callout is executed when an incoming DHCPv6
-   packet is received and its content is parsed. The sole argument -
-   query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
+   packet is received and its content is parsed. The sole argument
+   "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
    all information regarding incoming packet, including its source and
    destination addresses, the interface over which it was received, a list
    of all options present within and relay information.  All fields of
-   the Pkt6 object can be modified at this time, except data_. (data_
+   the "query6" object can be modified at this time, except data_. (data_
    contains the incoming packet as raw buffer. By the time this hook is
    reached, that information has already been parsed and is available though
-   other fields in the Pkt6 object.  For this reason, it doesn't make
-   sense to modify it.)
+   other fields in the Pkt6 object.  For this reason, modification of the
+   @c data_ field would have no effect.)
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
    drop the packet and start processing the next one.  The reason for the drop
@@ -107,13 +107,12 @@ packet processing. Hook points that are not specific to packet processing
    selected for the incoming packet. All parameters, addresses and
    prefixes will be assigned from that subnet. A callout can select a
    different subnet if it wishes so, the list of all subnets currently
-   configured being provided as 'subnet6collection'. The list itself must
+   configured being provided as "subnet6collection". The list itself must
    not be modified.
 
- - <b>Skip flag action</b>: If any callout installed on 'subnet6_select'
+ - <b>Skip flag action</b>: If any callout installed on "subnet6_select"
    sets the skip flag, the server will not select any subnet. Packet processing
-   will continue, but will be severely limited (i.e. only global options
-   will be assigned).
+   will continue, but will be severely limited.
 
 @subsection dhcpv6HooksLease6Select lease6_select
 
@@ -125,18 +124,18 @@ packet processing. Hook points that are not specific to packet processing
  - @b Description: This callout is executed after the server engine
    has selected a lease for client's request but before the lease
    has been inserted into the database. Any modifications made to the
-   isc::dhcp::Lease6 object will be stored in the lease's record in the
-   database. The callout should make sure that any modifications are
-   sanity checked as the server will use that data as is with no further
+   "lease6" object will affect the lease's record in the database.
+   The callout should make sure that any modifications are sanity
+   checked as the server will use that data as is, with no further
    checking.\n\n The server processes lease requests for SOLICIT and
-   REQUEST in a very similar way. The only major difference is that
-   for SOLICIT the lease is just selected; it is not inserted into
-   the database.  It is possible to distinguish between SOLICIT and
-   REQUEST by checking value of the fake_allocation flag: a value of true
-   means that the lease won't be inserted into the database (SOLICIT),
-   a value of false means that it will (REQUEST).
-
- - <b>Skip flag action</b>: If any callout installed on 'lease6_select'
+   REQUEST in a very similar way. The major difference is that
+   for SOLICIT the lease is only selected; it is not inserted into
+   the database.  The callouts can distinguish between the SOLICIT and
+   REQUEST by checking the value of the "fake_allocation" flag: a value
+   of true means that the lease won't be inserted into the database
+   (SOLICIT case), a value of false means that it will (REQUEST).
+
+ - <b>Skip flag action</b>: If any callout installed on "lease6_select"
    sets the skip flag, the server will not assign that particular lease.
    Packet processing will continue and the client may get other addresses
    or prefixes if it requested more than one address and/or prefix.
@@ -150,26 +149,26 @@ packet processing. Hook points that are not specific to packet processing
 
  - @b Description: This callout is executed when the server engine is
    about to renew an existing lease. The client's request is provided as
-   the query6 argument and the existing lease with the appropriate fields
-   already modified is given in the lease6 argument. The final argument,
+   the "query6" argument and the existing lease with the appropriate fields
+   already modified is given in the "lease6" argument. The final argument,
    ia_na, is the IA_NA option that will be sent back to the client.
-   Callouts installed on the lease6_renew may modify the content of
-   the lease6 object. Care should be taken however, as that modified
+   Callouts installed on the "lease6_renew" may modify the content of
+   the "lease6" object. Care should be taken however, as that modified
    information will be written to the database without any further
    checking. \n\n Although the envisaged usage assumes modification of T1,
    T2, preferred and valid lifetimes only, other parameters associated
-   with the lease may be modified as well. The only exception is the addr_
+   with the lease may be modified as well. The only exception is the @c addr_
    field, which must not be modified as it is used by the database to
    select the existing lease to be updated. Care should also be taken to
-   modify the ia_na argument to match any changes in the lease6 argument.
+   modify the "ia_na" argument to match any changes in the "lease6" argument.
    If a client sends more than one IA_NA option, callouts will be called
    separately for each IA_NA instance. The callout will be called only
    when the update is valid, i.e. conditions such as an invalid addresses
    or invalid iaid renewal attempts will not trigger this hook point.
 
- - <b>Skip flag action</b>: If any callout installed on 'lease6_renew'
+ - <b>Skip flag action</b>: If any callout installed on "lease6_renew"
    sets the skip flag, the server will not renew the lease. Under these
-   circumstances, the callout should modify the ia_na argument to reflect
+   circumstances, the callout should modify the "ia_na" argument to reflect
    this fact; otherwise the client will think the lease was renewed and continue
    to operate under this assumption.
 
@@ -181,12 +180,12 @@ packet processing. Hook points that are not specific to packet processing
 
  - @b Description: This callout is executed when the server engine is
    about to release an existing lease. The client's request is provided
-   as the query6 argument and the existing lease is given in the lease6
-   argument.  Although the lease6 structure may be modified, it doesn't
+   as the "query6" argument and the existing lease is given in the "lease6"
+   argument.  Although the "lease6" structure may be modified, it doesn't
    make sense to do so as it will be destroyed immediately the callouts
    finish execution.
 
- - <b>Skip flag action</b>: If any callout installed on 'lease6_release'
+ - <b>Skip flag action</b>: If any callout installed on "lease6_release"
    sets the skip flag, the server will not delete the lease, which will
    remain in the database until it expires. However, the server will send out
    the response back to the client as if it did.
@@ -197,22 +196,22 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
  - @b Description: This callout is executed when server's response
-   is about to be send back to the client. The sole argument - response6 -
-   contains a pointer to an isc::dhcp::Pkt6 object that contains the
+   is about to be send back to the client. The sole argument "response6"
+   contains a pointer to an @c isc::dhcp::Pkt6 object that contains the
    packet, with set source and destination addresses, interface over which
    it will be send, list of all options and relay information.  All fields
-   of the Pkt6 object can be modified at this time.  It should be noted that
-   unless the callout sets the skip flag (see below), anything placed in the
-   bufferOut_ field will be overwritten when the callout returns.
-   (bufferOut_ is scratch space used for constructing the packet.)
+   of the "response6" object can be modified at this time.  It should be
+   noted that unless the callout sets the skip flag (see below), anything
+   placed in the @c buffer_out_ field will be overwritten when the callout
+   returns. (buffer_out_ is scratch space used for constructing the packet.)
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server
-   will assume that the callout did pack the transaction-id, message type and
-   option objects into the bufferOut_ field and will skip packing part.
+   will assume that the callout did pack the "transaction-id", "message type"
+   and option objects into the @c buffer_out_ field and will skip packing part.
    Note that if the callout sets skip flag, but did not prepare the
    output buffer, the server will send a zero sized message that will be
    ignored by the client. If you want to drop the packet, please see
-   skip flag in the buffer6_send hook point.
+   skip flag in the "buffer6_send" hook point.
 
 @subsection dhcpv6HooksBuffer6Send buffer6_send
 
@@ -221,14 +220,14 @@ packet processing. Hook points that are not specific to packet processing
 
  - @b Description: This callout is executed when server's response is
    assembled into binary form and is about to be send back to the
-   client. The sole argument - response6 - contains a pointer to an
-   isc::dhcp::Pkt6 object that contains the packet, with set source and
+   client. The sole argument "response6" contains a pointer to an
+   @c isc::dhcp::Pkt6 object that contains the packet, with set source and
    destination addresses, interface over which it will be sent, list of
    all options and relay information. All options are already encoded
-   in bufferOut_ field. It doesn't make sense to modify anything but the
-   contents of bufferOut_ at this time (although if it is a requirement
+   in @c buffer_out_ field. It doesn't make sense to modify anything but the
+   contents of buffer_out_ at this time (although if it is a requirement
    to modify that data, it will probably be found easier to modify the
-   option objects in a callout attached to the pkt6_send hook).
+   option objects in a callout attached to the "pkt6_send" hook).
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server
    will drop this response packet. However, the original request packet

src/bin/dhcp6/dhcp6_srv.h

@@ -331,8 +331,6 @@ protected:
     /// not appropriate for the link the client is attached to, the server MAY
     /// send the IA with address lifetimes set to 0 or discard the message.
     ///
-    /// @param subnet subnet the sender belongs to
-    /// @param duid client's duid
     /// @param query client's message (Renew or Rebind)
     /// @param answer server's response to the client's message. This
     /// message should contain Client FQDN option being sent by the server

src/hooks/dhcp/user_chk/libdhcp_user_chk.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2014  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
@@ -35,19 +35,19 @@ sampled by an external consumer.
 
 ## User Registry Classes
 At the heart of the library is a class hierarchy centered around the class,
-user_chk::UserRegistry.  This class represents a maintainable, searchable
+@c user_chk::UserRegistry.  This class represents a maintainable, searchable
 registry of "known" users and their attributes.  It provides services to load,
 clear, and refresh the registry as well as to add, find, and remove users.
 
-Each entry in the registry is an instance of the class, user_chk::User. Users
-are uniquely identified by their user_chk::UserId. UserIds are comprised of
+Each entry in the registry is an instance of the class, @c user_chk::User. Users
+are uniquely identified by their @c user_chk::UserId. UserIds are comprised of
 data taken from the DHCP request. IPv4 users have a type of "HW_ADDR" and
 their id is the hardware address from the request.  IPv6 users have a type of
 "DUID" and their id is the DUID from the request.
 
 The registry may be manually populated or loaded from a source of data which
-implements the UserDataSource interface. Currently, a single implementation has
-been implemented, user_chk::UserFile. UserFile supports reading the registry
+implements the @c UserDataSource interface. Currently, a single implementation has
+been implemented, @c user_chk::UserFile. UserFile supports reading the registry
 from a text file in which each line is a user entry in JSON format.  Each entry
 contains the id type and user id along with optional attributes.  Attributes are
 essentially name/value pairs whose significance is left up to the calling layer.
@@ -59,7 +59,7 @@ The library implements callouts for packet receive, subnet select, and packet
 send for both IPv4 and IPv6.  Regardless of the protocol type, the process
 flow upon receipt of an inbound request is the same and is as follows:
 
--# pkt_receive callout is invoked
+-# "pkt_receive" callout is invoked
     -# Refresh the user registry
     -# Extract user id from DHCP request and store it to context
     -#  Look up user id in registry and store resultant user pointer to context
@@ -70,15 +70,16 @@ flow upon receipt of an inbound request is the same and is as follows:
     user and push the result to the context making it available to subsequent
     callouts.
 
--# subnet_select callout is invoked
+-# "subnet_select" callout is invoked
     -# Retrieve the user pointer from context
     -# If pointer is null (i.e. user is not registered), replace subnet
     selection with restricted subnet
 
     By convention, the last subnet in the collection of subnets available is
-    assumed to be the "restricted access" subnet. A more sophisticated mechanism    is likely to be needed.
+    assumed to be the "restricted access" subnet. A more sophisticated mechanism
+    is likely to be needed.
 
--# pkt_send callout is invoked:
+-# "pkt_send" callout is invoked:
     -# Retrieve the user id and user pointer from context
     -# If user is not null add the options based on user's attributes,
     otherwise use default user's attributes
@@ -96,7 +97,9 @@ Two steps are required in order to use the library:
 Currently, the library uses a hard coded pathname for the user registry defined
 in load_unload.cc:
 
+@code
     const char* registry_fname = "/tmp/user_chk_registry.txt";
+@endcode
 
 Each line in the file is a self-contained JSON snippet which must have the
 following two entries:
@@ -120,7 +123,8 @@ Sample user registry file is shown below:
 { "type" : "DUID", "id" : "00:01:00:01:19:ef:e6:3b:00:0c:01:02:03:06", "tftp_server" : "tftp.v6.example.com" }
 @endcode
 
-It is possible to specify additional attributes. They will be loaded and stored with the user's entry in the registry. This allows the library to be extended to perform additional actions based on these attributes.
+It is possible to specify additional attributes. They will be loaded and stored with the user's entry in the registry.
+This allows the library to be extended to perform additional actions based on these attributes.
 
 Upon start up the library will attempt to load this file.  If it does not exist
 the library will unload.

src/lib/asiolink/io_asio_socket.h

@@ -349,13 +349,7 @@ public:
 
     /// \brief Checks if the data received is complete.
     ///
-    /// \param staging Unused
-    /// \param length Unused
-    /// \param cumulative Unused
-    /// \param offset Unused.
-    /// \param expected Unused.
-    /// \param outbuff Unused.
-    ///
+    /// The parameters are unused.
     /// \return Always true
     virtual bool receiveComplete(const void*, size_t, size_t&, size_t&,
                                  size_t&, isc::util::OutputBufferPtr&)

src/lib/config/command-socket.dox

@@ -185,7 +185,8 @@ or HTTPS connection):
 Control Channel is connection oriented communication. In that sense it is
 different than all other communications supported so far in Kea. To facilitate
 connections, several mechanisms were implemented. Intially a single UNIX socket
-it opened (see isc::config::UnixCommandSocket). Its @ref
+it opened (see @c isc::config::UnixCommandSocket in
+src/lib/config/command_socket_factory.cc). Its @ref
 isc::config::UnixCommandSocket::receiveHandler callback method is
 installed in @ref isc::dhcp::IfaceMgr to process incoming connections. When the
 select call in @ref isc::dhcp::IfaceMgr::receive4 indicates that there is some data to be

src/lib/config/command_mgr.h

@@ -129,7 +129,8 @@ public:
     /// @brief Reads data from a socket, parses as JSON command and processes it
     ///
     /// This method is used to handle traffic on connected socket. This callback
-    /// is installed by the @ref isc::config::UnixCommandSocket::receiveHandler
+    /// is installed by the @c isc::config::UnixCommandSocket::receiveHandler
+    /// (located in the src/lib/config/command_socket_factory.cc)
     /// once the incoming connection is accepted. If end-of-file is detected, this
     /// method will close the socket and will uninstall itself from
     /// @ref isc::dhcp::IfaceMgr.

src/lib/dhcp/libdhcp++.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2014  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-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
@@ -28,35 +28,48 @@ add any server-specific code to libdhcp++ and use \ref libdhcpsrv instead.
 
 The following classes for packet manipulation are implemented:
 
-- isc::dhcp::Pkt4 - represents DHCPv4 packet.
-- isc::dhcp::Pkt6 - represents DHCPv6 packet.
+- isc::dhcp::Pkt4 - represents a DHCPv4 packet.
+- isc::dhcp::Pkt6 - represents a DHCPv6 packet.
 
-There are two pointer types defined: Pkt4Ptr and Pkt6Ptr. They are
-smart pointer and are using boost::shared_ptr. There are not const
-versions defined, as we assume that hooks can modify any aspect of
-the packet at almost any stage of processing.
+The following pointer types are defined: \c Pkt4Ptr and \c Pkt6Ptr. They are
+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 packets use collection of Option objects to represent DHCPv4
-and DHCPv6 options. The base class -- Option -- can be used 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 if the option is instantiated as v4 or v6
+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).
 
-There are many specialized classes that are intended to handle options with
-specific content:
+There are many specialized classes that are intended to handle options having
+specific formats:
 - isc::dhcp::Option4AddrLst -- DHCPv4 option, contains one or more IPv4 addresses;
 - isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses;
-- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR_OPTION (an option that
-                    contains IPv6 address with extra parameters);
+- isc::dhcp::Option4ClientFqdn -- DHCPv4 Client FQDN option;
+- isc::dhcp::Option6ClientFqdn -- DHCPv6 Client FQDN option;
+- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents an IAADDR option (an option that
+                              contains IPv6 address with extra parameters);
+- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents an IAPREFIX option (an option
+                                that contains IPv6 prefix in prefix delegation);
 - isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions.
-
-All options can store sub-options (i.e. options that are stored within option
-rather than in a message directly). This functionality is commonly used in
-DHCPv6, but is rarely used in DHCPv4. isc::dhcp::Option::addOption(),
-isc::dhcp::Option::delOption(), isc::dhcp::Option::getOption() can be used
-for that purpose.
+- isc::dhcp::Option6StatusCode -- DHCPv6 option, carries a status code to the client;
+- 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;
+- isc::dhcp::OptionVendor -- DHCPv4 or DHCPv6 option, carries Vendor Specific
+                             Information;
+- isc::dhcp::OptionVendorClass -- DHCPv4 or DHCPv6 option, contains vendor class
+                                  information.
+
+Various options can store sub-options (i.e. options that are stored within an
+option rather than in a message directly). This functionality is commonly used in
+DHCPv6, but is rarely used in DHCPv4. \ref isc::dhcp::Option::addOption(),
+\ref isc::dhcp::Option::delOption(), \ref isc::dhcp::Option::getOption() can
+be used to add, remove and retrieve sub-options from within an option.
 
 @section libdhcpRelay Relay v6 support in Pkt6
 
@@ -80,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 Pkt6::relay_info_ field, which is of type 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:
@@ -93,7 +106,7 @@ Client will transmit SOLICIT message. Relay1 will forward it as
 RELAY_FORW with SOLICIT in it. Relay2 forward it as RELAY_FORW with
 RELAY_FORW with SOLICIT in it. Finally the third relay will add yet
 another RELAY_FORW around it. The server will parse the packet and
-create Pkt6 object for it. Its relay_info_ will have 3
+create \c Pkt6 object for it. Its relay_info_ will have 3
 elements. Packet parsing is done in reverse order, compare to the
 order the packet traversed in the network.  The first element
 (relay_info_[0]) will represent relay3 information (the "last" relay or
@@ -103,40 +116,25 @@ the first relay (relay1) or in other words the one closest to the client.
 
 Packets sent by the server must maintain the same encapsulation order.
 This is easy to do - just copy data from client's message object into
-server's response object. See Pkt6::coyRelayInfo for details.
+server's response object. See @ref isc::dhcp::Pkt6::RelayInfo for details.
 
 @section libdhcpIfaceMgr Interface Manager
 
-Interface Manager (or IfaceMgr) is an abstraction layer about low-level
+Interface Manager (or IfaceMgr) is an abstraction layer for low-level
 network operations. In particlar, it provides information about existing
-network interfaces See isc::dhcp::IfaceMgr::Iface class and
-isc::dhcp::IfaceMgr::detectIfaces() and isc::dhcp::IfaceMgr::getIface().
-
-Currently there is interface detection is implemented in Linux and BSD.
-There are plans to implement such support for other OSes, but they
-remain low priority for now.
+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 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.
-
-For systems that interface detection is not supported on, there is a stub
-mechanism implemented. It assumes that interface name is read from a text
-file. This is a temporary solution and will be removed as soon as proper
-interface detection is implemented. It is not going to be developed further.
-To use this feature, store interfaces.txt file. It uses a simple syntax.
-Each line represents an interface name, followed by IPv4 or IPv6 address
-that follows it. This is usually link-local IPv6 address that the server
-should bind to. In theory this mechanism also supports IPv4, but it was
-never tested. The code currently supports only a single interface defined
-that way.
+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
-(isc::dhcp::IfaceMgr::send(), 2 overloads) and reception
-(isc::dhcp::IfaceMgr::receive4() and isc::dhcp::IfaceMgr::receive6()).
-Note that receive4() and receive6() methods may return NULL, e.g.
-when timeout is reached or if dhcp daemon receives a signal.
+(\ref isc::dhcp::IfaceMgr::send(), 2 overloads) and reception
+(\ref isc::dhcp::IfaceMgr::receive4() and \ref isc::dhcp::IfaceMgr::receive6()).
+Note that \c receive4() and \c receive6() methods may return NULL, e.g.
+when timeout is reached or if the DHCP daemon receives a signal.
 
 @section libdhcpPktFilter Switchable Packet Filter objects used by Interface Manager
 

src/lib/dhcp/std_option_defs.h

@@ -28,7 +28,6 @@ namespace {
 /// of a definition for option comprising a record of data fields.
 ///
 /// @param name name of the array being declared.
-/// @param types data types of fields that belong to the record.
 #ifndef RECORD_DECL
 #define RECORD_DECL(name, ...) const OptionDataType name[] = { __VA_ARGS__ }
 #endif

src/lib/dhcpsrv/alloc_engine.h

@@ -408,9 +408,9 @@ public:
     /// response to SOLICIT).
     ///
     /// This method uses host reservation if ctx.host_ is set. The easy way to
-    /// set it is to call @ref AllocEngine::findReservation(ctx). The host reservation
-    /// is convenient, but incurs performance penalty, so it can be tweaked on
-    /// a per subnet basis. There are three possible modes:
+    /// set it is to call @ref isc::dhcp::AllocEngine::findReservation(ctx).
+    /// The host reservation is convenient, but incurs performance penalty,
+    /// so it can be tweaked on a per subnet basis. There are three possible modes:
     /// 1. disabled (no host reservation at all). This is the most performant one
     /// as the code can skip all checks;
     /// 2. out-of-pool (only reservations that are outside

src/lib/dhcpsrv/alloc_engine_log.h

@@ -21,7 +21,7 @@
 namespace isc {
 namespace dhcp {
 
-///@{
+//@{
 /// \brief Logging levels for the @c AllocEngine.
 ///
 /// Defines the levels used to output debug messages from the @c AllocEngine.
@@ -45,7 +45,7 @@ const int ALLOC_ENGINE_DBG_TRACE_DETAIL = DBGLVL_TRACE_DETAIL;
 /// Messages logged at this level will contain detailed results.
 const int ALLOC_ENGINE_DBG_TRACE_DETAIL_DATA = DBGLVL_TRACE_DETAIL_DATA;
 
-///@}
+//@}
 
 /// @brief Logger for the @c AllocEngine..
 ///

src/lib/dhcpsrv/database_backends.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2012  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-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
@@ -41,7 +41,7 @@
 
   @section dhcpdb-instantiation Instantiation of Lease Managers
 
-  A lease manager is instantiated through the LeaseMgrFactory class.  This
+  A lease manager is instantiated through the @c LeaseMgrFactory class.  This
   has three methods:
 
   - isc::dhcp::LeaseMgrFactory::create - Creates a singleton Lease

src/lib/dhcpsrv/libdhcpsrv.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2012, 2014 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-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
@@ -15,27 +15,35 @@
 /**
  @page libdhcpsrv libdhcpsrv - Server DHCP library
 
-This library contains code useful for DHCPv4 and DHCPv6 server operations, like
-Lease Manager that stores leases information, configuration manager that stores
-configuration etc. The code here is server specific. For generic (useful in
-server, client, relay and other tools like perfdhcp) code, please see
+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 of 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
+- isc::dhcp::CfgMgr - configuration manager that holds DHCP specific
   configuration information (subnets, pools, options, timer values etc.) in
   easy to use format.
-- 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. 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 the
-only available backend is MySQL (see \ref isc::dhcp::MySqlLeaseMgr).
+backends are derived from the base class isc::dhcp::LeaseMgr. Currently Kea
+supports three backends, implemented in the following classes:
+
+- 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
 
@@ -77,10 +85,6 @@ configuration. For example: the value of 1 identifies an immediate
 predecessor of the current configuration, the value of 2 identifies the
 one that occurred before it etc.
 
-@todo Currently, only a subset of configuration information is stored in
-the \ref isc::dhcp::SrvConfig object. Kea developers are actively working
-on migrating the other configuration parameters to it.
-
 @section hostmgr Host Manager
 
 Host Manager implemented by the \ref isc::dhcp::HostMgr is a singleton object

src/lib/dhcpsrv/parsers/dhcp_parsers.h

@@ -958,7 +958,7 @@ protected:
     /// The elements currently supported are:
     /// -# ip-address
     ///
-    /// @param config_id is the "item_name" for a specific member element of
+    /// @param parser is the "item_name" for a specific member element of
     /// the "relay" specification.
     ///
     /// @return returns a pointer to newly created parser.
@@ -1058,6 +1058,8 @@ protected:
     /// Allowed values are "disabled", "off" (alias for disabled),
     /// "out-of-pool" and "all". See Subnet::HRMode for their exact meaning.
     ///
+    /// @param txt Host Reservation mode in the textual form.
+    ///
     /// @throw BadValue if the text cannot be converted.
     ///
     /// @param text representation for conversion

src/lib/hooks/hooks_component_developer.dox

@@ -90,8 +90,8 @@ The following sections will describe these tasks in more detail.
 @section hooksComponentDefinition Determining the Hook Points
 
 Before any other action takes place, the location of the hook points
-in the code need to be determined.  This of course depends on the
-component but as a general guideline, hook locations should be chosen
+in the code need to be determined.  This, of course, depends on the
+component but, as a general guideline, hook locations should be located
 where a callout is able to obtain useful information from Kea and/or
 affect processing.  Typically this means at the start or end of a major
 step in the processing of a request, at a point where either useful
@@ -121,7 +121,7 @@ subject to certain restrictions (see below).
 Before the callouts at any hook point are called and any user libraries
 loaded - so typically during component initialization - the component must
 register the names of all the hooks.  The registration is done using
-the static method isc::hooks::HooksManager::registerHook():
+the static method @c isc::hooks::HooksManager::registerHook():
 
 @code
 
@@ -130,7 +130,7 @@ the static method isc::hooks::HooksManager::registerHook():
     int example_index = HooksManager::registerHook("lease_allocate");
 @endcode
 
-The name of the hook is passed as the sole argument to the registerHook()
+The name of the hook is passed as the sole argument to the @c registerHook()
 method.  The value returned is the index of that hook point and should
 be retained - it is needed to call the callouts attached to that hook.
 
@@ -142,7 +142,7 @@ unregistering a hook and there is no need to do so.
 In some components, it may be convenient to set up a single initialization
 function that registers all hooks.  For others, it may be more convenient
 for each module within the component to perform its own initialization.
-Since the isc::hooks::HooksManager object is a singleton and is created when first
+Since the @c isc::hooks::HooksManager object is a singleton and is created when first
 accessed, a useful trick is to automatically register the hooks when
 the module is loaded.
 
@@ -197,7 +197,7 @@ However, the following guidelines should be observed:
 
 - The names <b>context_create</b> and <b>context_destroy</b> are reserved to
 the hooks system and are automatically registered: an attempt to register
-one of these will lead to a isc::hooks::DuplicateHook exception being thrown.
+one of these will lead to a @c isc::hooks::DuplicateHook exception being thrown.
 
 - The hook name should be a valid "C" function name.  If a user gives a
 callout the same name as one of the hooks, the hooks framework will
@@ -224,16 +224,16 @@ Each user callout has the signature:
 int callout_name(isc::hooks::CalloutHandle& handle);
 @endcode
 
-The isc::hooks::CalloutHandle object is the object used to pass data to
+The @c isc::hooks::CalloutHandle object is the object used to pass data to
 and from the callout.  This holds the data as a set of name/value pairs,
 each pair being considered an argument to the callout.  If there are
-multiple callouts attached to a hook, the CalloutHandle is passed to
+multiple callouts attached to a hook, the @c CalloutHandle is passed to
 each in turn. Should a callout modify an argument, the updated data is
 passed subsequent callouts (each of which could also modify it) before
 being returned to the component.
 
 Two methods are provided to get and set the arguments passed to
-the callout called (naturally enough) getArgument and SetArgument.
+the callout called (naturally enough) @c getArgument and @c setArgument.
 Their usage is illustrated by the following code snippets.
 
 @code
@@ -254,26 +254,26 @@ Their usage is illustrated by the following code snippets.
     handle_ptr->getArgument("inpacket", pktptr);
 @endcode
 
-As can be seen "getArgument" is used to retrieve data from the
-CalloutHandle, and "setArgument" used to put data into it.  If a callout
+As can be seen @c getArgument is used to retrieve data from the
+@c CalloutHandle, and @c setArgument used to put data into it.  If a callout
 wishes to alter data and pass it back to the component, it should retrieve
 the data with getArgument, modify it, and call setArgument to send
 it back.
 
 There are a couple points to be aware of:
 
-- The data type of the variable in the call to getArgument must
+- The data type of the variable in the call to @c getArgument must
 match the data type of the variable passed to the corresponding
-setArgument <B>exactly</B>: using what would normally be considered
+@c setArgument <B>exactly</B>: using what would normally be considered
 to be a "compatible" type is not enough.  For example, if the callout
-passed an argument back to the component as an "int" and the component
-attempted to retrieve it as a "long", an exception would be thrown even
-though any value that can be stored in an "int" will fit into a "long".
+passed an argument back to the component as an @c int and the component
+attempted to retrieve it as a @c long, an exception would be thrown even
+though any value that can be stored in an @c int will fit into a @c long.
 This restriction also applies the "const" attribute but only as applied to
-data pointed to by pointers, e.g. if an argument is defined as a "char*",
+data pointed to by pointers, e.g. if an argument is defined as a @c char*,
 an exception will be thrown if an attempt is made to retrieve it into
-a variable of type "const char*".  (However, if an argument is set as a
-"const int", it can be retrieved into an "int".)  The documentation of
+a variable of type @c const @c char*.  (However, if an argument is set as a
+@c const @c int, it can be retrieved into an @c int.)  The documentation of
 a hook point should detail the exact data type of each argument.
 
 - If a pointer to an object is passed to a callout (either a "raw"
@@ -285,7 +285,7 @@ This can be avoided by passing a pointer to a "const" object.
 @subsection hooksComponentSkipFlag The Skip Flag
 
 Although information is passed back to the component from callouts through
-CalloutHandle arguments, a common action for callouts is to inform the component
+@c CalloutHandle arguments, a common action for callouts is to inform the component
 that its flow of control should be altered.  For example:
 
 - In the DHCP servers, there is a hook at the point at which a lease is
@@ -298,9 +298,9 @@ that its flow of control should be altered.  For example:
   against a blacklist.  If the address is on the list, the callout could set
   the skip flag to indicate to the server that the packet should be dropped.
 
-For ease of processing, the CalloutHandle contains
-two methods, isc::hooks::CalloutHandle::getSkip() and
-isc::hooks::CalloutHandle::setSkip().  It is only meaningful for the
+For ease of processing, the @c CalloutHandle contains
+two methods, @c isc::hooks::CalloutHandle::getSkip() and
+@c isc::hooks::CalloutHandle::setSkip().  It is only meaningful for the
 component to use the "get" method.  The skip flag is cleared by the hooks
 framework when the component requests that callouts be executed, so any
 value set by the component is lost.  Callouts can both inspect the flag (it
@@ -325,14 +325,14 @@ if (! handle_ptr->getSkip()) {
 
 @subsection hooksComponentGettingHandle Getting the Callout Handle
 
-The CalloutHandle object is linked to the loaded libraries
+The @c CalloutHandle object is linked to the loaded libraries
 for lifetime reasons (described below).  Components
-should retrieve a isc::hooks::CalloutHandle using
-isc::hooks::HooksManager::createCalloutHandle():
+should retrieve a @c isc::hooks::CalloutHandle using
+@c isc::hooks::HooksManager::createCalloutHandle():
 @code
     CalloutHandlePtr handle_ptr = HooksManager::createCalloutHandle();
 @endcode
-(isc::hooks::CalloutHandlePtr is a typedef for a Boost shared pointer to a
+(@c isc::hooks::CalloutHandlePtr is a typedef for a Boost shared pointer to a
 CalloutHandle.)  The CalloutHandle so retrieved may be used for as
 long as the libraries are loaded.
 
@@ -350,14 +350,14 @@ in a future version.)
 @subsection hooksComponentCallingCallout Calling the Callout
 
 Calling the callout is a simple matter of executing the
-isc::hooks::HooksManager::callCallouts() method for the hook index in
-question.  For example, with the hook index pkt_sent defined as above,
+@c isc::hooks::HooksManager::callCallouts() method for the hook index in
+question.  For example, with the hook index "pkt_sent" defined as above,
 the hook can be executed by:
 @code
     HooksManager::callCallouts(pkt_sent, *handle_ptr);
 @endcode
 ... where "*handle_ptr" is a reference (note: not a pointer) to the
-isc::hooks::CalloutHandle object holding the arguments.  No status code
+@c isc::hooks::CalloutHandle object holding the arguments.  No status code
 is returned.  If a component needs to get data returned (other than that
 provided by the "skip" flag), it should define an argument through which
 the callout can do so.
@@ -365,9 +365,9 @@ the callout can do so.
 @subsubsection hooksComponentConditionalCallout Conditionally Calling Hook Callouts
 
 Most hooks in a component will not have callouts attached to them. To
-avoid the overhead of setting up arguments in the CalloutHandle, a
+avoid the overhead of setting up arguments in the @c CalloutHandle, a
 component can check for callouts before doing that processing using
-isc::hooks::HooksManager::calloutsPresent().  Taking the index of a
+@c isc::hooks::HooksManager::calloutsPresent().  Taking the index of a
 hook as its sole argument, the function returns true if there are any
 callouts attached to the hook and false otherwise.
 
@@ -390,33 +390,33 @@ if (HooksManager::calloutsPresent(lease_hook_index)) {
 
 Once hooks are defined, all the hooks code described above will
 work, even if no libraries are loaded (and even if the library
-loading method is not called).  The CalloutHandle returned by
-isc::hooks::HooksManager::createCalloutHandle() will be valid,
-isc::hooks::HooksManager::calloutsPresent() will return false for every
-index, and isc::hooks::HooksManager::callCallouts() will be a no-op.
+loading method is not called).  The @c CalloutHandle returned by
+@c isc::hooks::HooksManager::createCalloutHandle() will be valid,
+@c isc::hooks::HooksManager::calloutsPresent() will return false for every
+index, and @c isc::hooks::HooksManager::callCallouts() will be a no-op.
 
 However, if user libraries are specified in the Kea configuration,
 the component should load them.  (Note the term "libraries": the hooks
 framework allows multiple user libraries to be loaded.) This should take
 place after the component's configuration has been read, and is achieved
-by the isc::hooks::HooksManager::loadLibraries() method.  The method is
+by the @c isc::hooks::HooksManager::loadLibraries() method.  The method is
 passed a vector of strings, each giving the full file specification of
 a user library:
 @code
     std::vector<std::string> libraries = ... // Get array of libraries
     bool success = HooksManager::loadLibraries(libraries);
 @endcode
-loadLibraries() returns a boolean status which is true if all libraries
+@c loadLibraries() returns a boolean status which is true if all libraries
 loaded successfully or false if one or more failed to load.  Appropriate
 error messages will have been logged in the latter case, the status
 being more to allow the developer to decide whether the execution
 should proceed in such circumstances.
 
-If loadLibraries() is called a second or subsequent time (as a result
+If @c loadLibraries() is called a second or subsequent time (as a result
 of a reconfiguration), all existing libraries are unloaded and a new
 set loaded.  Libraries can be explicitly unloaded either by calling
-isc::hooks::HooksManager::unloadLibraries() or by calling
-loadLibraries() with an empty vector as an argument.
+@c isc::hooks::HooksManager::unloadLibraries() or by calling
+@c loadLibraries() with an empty vector as an argument.
 
 @subsection hooksComponentUnloadIssues Unload and Reload Issues
 
@@ -429,7 +429,7 @@ In many operating systems, heap storage allowed by a shared library will
 lie in the virtual address allocated to the library.  This has implications
 in the hooks framework because:
 
-- Argument information stored in a CalloutHandle by a callout in a library
+- Argument information stored in a @c CalloutHandle by a callout in a library
 may lie in the library's address space.
 - Data modified in objects passed as arguments may lie in the address
 space.  For example, it is common for a DHCP callout to add "options"
@@ -467,16 +467,16 @@ found in @ref hooksdgDevelopersGuide.)
 
 A component can associate with a hook callouts that run either before
 user-registered callouts or after them.  Registration is done via a
-isc::hooks::LibraryHandle object, a reference to one being obtained
-through the methods isc::hooks::HooksManager::preCalloutLibraryHandle()
+@c isc::hooks::LibraryHandle object, a reference to one being obtained
+through the methods @c isc::hooks::HooksManager::preCalloutLibraryHandle()
 (for a handle to register callouts to run before the user library
-callouts) or isc::hooks::HooksManager::postCalloutLibraryHandle() (for
+callouts) or @c isc::hooks::HooksManager::postCalloutLibraryHandle() (for
 a handle to register callouts to run after the user callouts).  Use of
-the LibraryHandle to register and deregister callouts is described in
+the @c LibraryHandle to register and deregister callouts is described in
 @ref hooksdgLibraryHandle.
 
 Finally, it should be noted that callouts registered in this way only
-remain registered until the next call to isc::hooks::loadLibraries().
+remain registered until the next call to @c isc::hooks::loadLibraries().
 It is up to the component to re-register the callouts after this
 method has been called.
 

src/lib/hooks/hooks_maintenance.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
@@ -58,8 +58,8 @@
  The @ref isc::hooks::CalloutHandle has two functions: passing arguments
  between the Kea component and the user-written library, and storing
  per-request context between library calls.  In both cases the data is
- stored in a std::map structure, keyed by argument (or context item) name.
- The actual data is stored in a boost::any object, which allows any
+ stored in a @c std::map structure, keyed by argument (or context item) name.
+ The actual data is stored in a @c boost::any object, which allows any
  data type to be stored, although a penalty for this flexibility is
  the restriction (mentioned in the @ref hooksdgDevelopersGuide) that
  the type of data retrieved must be identical (and not just compatible)
@@ -149,11 +149,11 @@
  time and is used to tag the callout pointers.  It is discussed
  further below.
 
- As the LibraryManager provides all the methods needed to manage the
- shared library, it is the natural home for the static validateLibrary()
+ As the @c LibraryManager provides all the methods needed to manage the
+ shared library, it is the natural home for the static @c validateLibrary()
  method. The function called the parsing of the Kea configuration, when
  the "hooks-libraries" element is processed. It checks that shared library
- exists, that it can be opened, that it contains the "version()" function
+ exists, that it can be opened, that it contains the @c version() function
  and that that function returns a valid value. It then closes the shared
  library and returns an appropriate indication as to the library status.
 
@@ -164,32 +164,32 @@
  of them. The collection of LibraryManagers is managed by the
  @ref isc::hooks::LibraryManagerCollection object which, in most
  cases has a method corresponding to a @ref hooksmgLibraryManager
- method, e.g. it has a loadLibraries() that corresponds to the @ref
+ method, e.g. it has a @c loadLibraries() that corresponds to the @ref
  hooksmgLibraryManager's loadLibrary() call. As would be expected, methods
- on the LibraryManagerCollection iterate through all specified libraries,
+ on the @c LibraryManagerCollection iterate through all specified libraries,
  calling the corresponding LibraryManager method for each library.
 
- One point of note is that LibraryManagerCollection operates on an "all
- or none" principle. When loadLibraries() is called, on exit either all
+ One point of note is that @c LibraryManagerCollection operates on an "all
+ or none" principle. When @c loadLibraries() is called, on exit either all
  libraries have been successfully opened or none of them have. There
  is no use-case in Kea where, after a user has specified the shared
  libraries they want to load, the system will operate with only some of
  them loaded.
 
- The LibraryManagerCollection is the place where each library's index is set.
+ The @c LibraryManagerCollection is the place where each library's index is set.
  Each library is assigned a number ranging from 1 through to the number
  of libraries being loaded.  As mentioned in the previous section, this
  index is used to tag callout pointers, something that is discussed
  in the next section.
 
  (Whilst on the subject of library index numbers, two additional
- numbers - 0 and INT_MAX - are also valid as "current library index".
+ numbers - 0 and @c INT_MAX - are also valid as "current library index".
  For flexibility, the Kea component is able to register its own
  functions as hook callouts.  It does this by obtaining a suitable @ref
  hooksmgLibraryHandle from the @ref hooksmgHooksManager.  A choice
  of two is available: one @ref hooksmgLibraryHandle (with an index
  of 0) can be used to register a callout on a hook to execute before
- any user-supplied callouts.  The second (with an index of INT_MAX)
+ any user-supplied callouts.  The second (with an index of @c INT_MAX)
  is used to register a callout to run after user-specified callouts.
  Apart from the index number, the hooks framework does not treat these
  callouts any differently from user-supplied ones.)
@@ -209,7 +209,7 @@
  function (and prior to registering the standard callbacks).
 
  The situation is slightly more complex when a callout is executing. In
- order to execute a callout, the CalloutManager's callCallouts()
+ order to execute a callout, the CalloutManager's @c callCallouts()
  method must be called. This iterates through the callout vector for
  a hook and for each element in the vector, uses the "library index"
  part of the pair to set the "current library index" before calling the
@@ -282,8 +282,8 @@
 
  Static linking poses a problem for dynamically-loaded hooks libraries
  as some of the code in them - in particular the hooks framework and
- the logging code - depend on global objects created within the BIND
- 10 libraries.  In the normal course of events (Kea linked against
+ the logging code - depend on global objects created within the Kea
+ libraries.  In the normal course of events (Kea linked against
  shared libraries), when Kea is run and the operating system loads
  a Kea shared library containing a global object, address space
  is assigned for it.  When the hooks framework loads a user-library
@@ -315,16 +315,16 @@
  the relevant Kea server; this information is not available in the
  singleton created in the user's hooks library.
 
- Within the code users by the user's hooks library, the ServerHooks
+ Within the code users by the user's hooks library, the @c ServerHooks
  object is used by @ref isc::hooks::CalloutHandle and @ref
  isc::hooks::CalloutManager objects.  Both these objects are passed to the
  hooks library code when a callout is called: the former directly through
  the callout argument list, the latter indirectly as a pointer to it is
  stored in the CalloutHandle.  This allows a solution to the problem:
- instead of accessing the singleton via ServerHooks::getServerHooks(),
+ instead of accessing the singleton via @c ServerHooks::getServerHooks(),
  the constructors of these objects store a reference to the singleton
- ServerHooks when they are created and use that reference to access
- ServerHooks data.  Since both CalloutHandle and CalloutManager are
+ @c ServerHooks when they are created and use that reference to access
+ @c ServerHooks data.  Since both @c CalloutHandle and @c CalloutManager are
  created in the statically-linked Kea server, use of the reference
  means that it is the singleton within the server - and not the one
  within the user's hooks library - that is referenced.
@@ -349,8 +349,8 @@
  log4cplus shared library, item 1 - the static initialization of the log4cplus
  global variables is performed once.
 
- The next two tasks - static initialization of the messages in the BIND
- 10 libraries and the static initialization of the logging framework -
+ The next two tasks - static initialization of the messages in the Kea
+ libraries and the static initialization of the logging framework -
  are performed twice, once in the context of the Kea server and
  once in the context of the hooks library.  For this reason, run-time
  initialization of the logging framework needs to be performed twice,
@@ -359,7 +359,7 @@
  initialization code also performs the last task, initialization of
  log4cplus, something that causes problems if executed more than once.
 
- To get round this, the function isc::hooks::hooksStaticLinkInit()
+ To get round this, the function @ref isc::hooks::hooksStaticLinkInit()
  has been written.  It executes the only part of the logging framework
  run-time initialization that actually pertains to the logging framework
  and not log4cplus, namely loading the message dictionary with the
@@ -368,7 +368,7 @@
  initialized Kea.  (In fact, running it against a dynamically-linked
  Kea should have no effect, as the load operation discards any duplicate
  message entries.)  The hooks library tests do this, the code being
- conditionally compiled within a test of the USE_STATIC_LINK macro, set
+ conditionally compiled within a test of the @c USE_STATIC_LINK macro, set
  by the configure script.
 
  @note Not everything is completely rosy with logging and static linking.
@@ -376,7 +376,7 @@
  user-written hooks library is run by a statically-linked Kea and then
  unloaded.  As far as can be determined, on unload the system attempts to
  delete the same logger twice.  This is alleviated by explicitly clearing
- the loggerptr_ variable in the isc::log::Logger destructor, but there
+ the loggerptr_ variable in the @ref isc::log::Logger destructor, but there
  is a suspicion that some memory might be lost in these circumstances.
  This is still under investigation.
 */

src/lib/hooks/hooks_user.dox

@@ -100,11 +100,11 @@ shared library and loaded by Kea into its address space.
 To illustrate how to write code that integrates with Kea, we will
 use the following (rather contrived) example:
 
-The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
+<i>The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
 (as well as to pass them other information such as the address of DNS
 servers).  We will suppose that we need to classify clients requesting
 IPv4 addresses according to their hardware address, and want to log both
-the hardware address and allocated IP address for the clients of interest.
+the hardware address and allocated IP address for the clients of interest.</i>
 
 The following sections describe how to implement these requirements.
 The code presented here is not efficient and there are better ways of
@@ -282,11 +282,11 @@ int callout(CalloutHandle& handle);
 @endcode
 
 (As before, the callout is declared with "C" linkage.)  Information is passed
-between Kea and the callout through name/value pairs in the CalloutHandle
+between Kea and the callout through name/value pairs in the @c CalloutHandle
 object. The object is also used to pass information between callouts on a
 per-request basis. (Both of these concepts are explained below.)
 
-A callout returns an "int" as a status return.  A value of 0 indicates
+A callout returns an @c int as a status return.  A value of 0 indicates
 success, anything else signifies an error.  The status return has no
 effect on server processing; the only difference between a success
 and error code is that if the latter is returned, the server will
@@ -296,7 +296,7 @@ error information to the Kea logging system.
 
 @subsubsection hooksdgArguments Callout Arguments
 
-The CalloutHandle object provides two methods to get and set the
+The @c CalloutHandle object provides two methods to get and set the
 arguments passed to the callout.  These methods are called (naturally
 enough) getArgument and SetArgument.  Their usage is illustrated by the
 following code snippets.
@@ -336,27 +336,27 @@ In the callout
     handle.setArgument("data_count", number);
 @endcode
 
-As can be seen "getArgument" is used to retrieve data from the
-CalloutHandle, and setArgument used to put data into it.  If a callout
+As can be seen @c getArgument is used to retrieve data from the
+@c CalloutHandle, and @c setArgument used to put data into it.  If a callout
 wishes to alter data and pass it back to the server, it should retrieve
-the data with getArgument, modify it, and call setArgument to send
+the data with @c getArgument, modify it, and call @c setArgument to send
 it back.
 
 There are several points to be aware of:
 
-- the data type of the variable in the call to getArgument must match
-the data type of the variable passed to the corresponding setArgument
+- the data type of the variable in the call to @c getArgument must match
+the data type of the variable passed to the corresponding @c setArgument
 <B>exactly</B>: using what would normally be considered to be a
 "compatible" type is not enough.  For example, if the server passed
-an argument as an "int" and the callout attempted to retrieve it as a
-"long", an exception would be thrown even though any value that can
-be stored in an "int" will fit into a "long".  This restriction also
+an argument as an @c int and the callout attempted to retrieve it as a
+@c long, an exception would be thrown even though any value that can
+be stored in an @c int will fit into a @c long.  This restriction also
 applies the "const" attribute but only as applied to data pointed to by
-pointers, e.g. if an argument is defined as a "char*", an exception will
+pointers, e.g. if an argument is defined as a @c char*, an exception will
 be thrown if an attempt is made to retrieve it into a variable of type
-"const char*".  (However, if an argument is set as a "const int", it can
-be retrieved into an "int".)  The documentation of each hook point will
-detail the data type of each argument.
+@c const @c char*.  (However, if an argument is set as a @c const @c int,
+it can be retrieved into an @c int.)  The documentation of each hook
+point will detail the data type of each argument.
 - Although all arguments can be modified, some altered values may not
 be read by the server. (These would be ones that the server considers
 "read-only".) Consult the documentation of each hook to see whether an
@@ -371,8 +371,8 @@ parameters can be modified.  As a general rule:
 
 - Do not alter arguments unless you mean the change to be reflected in
 the server.
-- If you alter an argument, call CalloutHandle::setArgument to update the
-value in the CalloutHandle object.
+- If you alter an argument, call @c CalloutHandle::setArgument to update the
+value in the @c CalloutHandle object.
 
 @subsubsection hooksdgSkipFlag The "Skip" Flag
 
@@ -391,7 +391,7 @@ is a server where a callout inspects the hardware address of the client
 sending the packet and compares it against a black list; if the address
 is on it, the callout notifies the server to drop the packet.
 
-To handle these common cases, the CalloutHandle has a "skip" flag.
+To handle these common cases, the @c CalloutHandle has a "skip" flag.
 This is set by a callout when it wishes the server to skip normal
 processing.  It is set false by the hooks framework before callouts on a
 hook are called.  If the flag is set on return, the server will take the
@@ -427,7 +427,7 @@ Future developments may have the server processing multiple packets
 simultaneously, or to suspend processing on a packet and resume it at
 a later time after other packets have been processed.
 
-As well as argument information, the CalloutHandle object can be used by
+As well as argument information, the @c CalloutHandle object can be used by
 callouts to attach information to a packet being handled by the server.
 This information (known as "context") is not used by the server: its purpose
 is to allow callouts to pass information between one another on a
@@ -441,9 +441,9 @@ simultaneously: callouts can effectively attach data to a packet that
 follows the packet around the system.
 
 Context information is held as name/value pairs in the same way
-as arguments, being accessed by the pair of methods setContext and
-getContext.  They have the same restrictions as the setArgument and
-getArgument methods - the type of data retrieved from context must
+as arguments, being accessed by the pair of methods @c setContext and
+@c getContext.  They have the same restrictions as the @c setArgument and
+@c getArgument methods - the type of data retrieved from context must
 <B>exactly</B> match the type of the data set.
 
 The example in the next section illustrates their use.
@@ -457,8 +457,9 @@ do this in one callout, for this example we'll use two:
 
 - pkt4_receive - a callout on this hook is invoked when a packet has been
 received and has been parsed.  It is passed a single argument, "query4"
-which is an isc::dhcp::Pkt4 object (representing a DHCP v4 packet).
-We will do the classification here.
+which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the
+isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the
+classification here.
 
 - pkt4_send - called when a response is just about to be sent back to
 the client.  It is passed a single argument "response4".  This is the
@@ -521,7 +522,7 @@ int pkt4_receive(CalloutHandle& handle) {
 }
 @endcode
 
-The pkt4_receive callout placed the hardware address of an interesting client in
+The "pkt4_receive" callout placed the hardware address of an interesting client in
 the "hwaddr" context for the packet.  Turning now to the callout that will
 write this information to the log file:
 
@@ -757,12 +758,12 @@ to initialize per-request context. The second is called after all
 server-defined hooks have been processed, and is to allow a library to
 tidy up.
 
-As an example, the pkt4_send example above required that the code
+As an example, the "pkt4_send" example above required that the code
 check for an exception being thrown when accessing the "hwaddr" context
 item in case it was not set.  An alternative strategy would have been to
 provide a callout for the "context_create" hook and set the context item
 "hwaddr" to an empty string. Instead of needing to handle an exception,
-pkt4_send would be guaranteed to get something when looking for
+"pkt4_send" would be guaranteed to get something when looking for
 the hwaddr item and so could write or not write the output depending on
 the value.
 
@@ -771,7 +772,7 @@ automatically deletes context. An example where it could be required
 is where memory has been allocated by a callout during the processing
 of a request and a raw pointer to it stored in the context object. On
 destruction of the context, that memory will not be automatically
-released. Freeing in the memory in the "context_destroy callout will solve
+released. Freeing in the memory in the "context_destroy" callout will solve
 that problem.
 
 Actually, when the context is destroyed, the destructor
@@ -786,8 +787,8 @@ Here it is assumed that the hooks library is performing some form of
 security checking on the packet and needs to maintain information in
 a user-specified "SecurityInformation" object. (The details of this
 fictitious object are of no concern here.) The object is created in
-the context_create callout and used in both the pkt4_receive and the
-pkt4_send callouts.
+the "context_create" callout and used in both the "pkt4_receive" and the
+"pkt4_send" callouts.
 
 @code
 // Storing information in a "raw" pointer.  Assume that the
@@ -808,7 +809,7 @@ int context_create(CalloutHandle& handle) {
 // Callouts that use the context
 int pkt4_receive(CalloutHandle& handle) {
     // Retrieve the pointer to the SecurityInformation object
-    SecurityInformation si;
+    SecurityInformation* si;
     handle.getContext("security_information", si);
         :
         :
@@ -821,7 +822,7 @@ int pkt4_receive(CalloutHandle& handle) {
 
 int pkt4_send(CalloutHandle& handle) {
     // Retrieve the pointer to the SecurityInformation object
-    SecurityInformation si;
+    SecurityInformation* si;
     handle.getContext("security_information", si);
         :
         :
@@ -831,11 +832,11 @@ int pkt4_send(CalloutHandle& handle) {
 }
 
 // Context destruction.  We need to delete the pointed-to SecurityInformation
-// object because we will lose the pointer to it when the CalloutHandle is
+// object because we will lose the pointer to it when the @c CalloutHandle is
 // destroyed.
 int context_destroy(CalloutHandle& handle) {
     // Retrieve the pointer to the SecurityInformation object
-    SecurityInformation si;
+    SecurityInformation* si;
     handle.getContext("security_information", si);
 
     // Delete the pointed-to memory.
@@ -843,7 +844,7 @@ int context_destroy(CalloutHandle& handle) {
 }
 @endcode
 
-The requirement for the context_destroy callout can be eliminated if
+The requirement for the "context_destroy" callout can be eliminated if
 a Boost shared ptr is used to point to the allocated memory:
 
 @code
@@ -865,7 +866,7 @@ int context_create(CalloutHandle& handle) {
 }
 
 // Other than the data type, a shared pointer has similar semantics to a "raw"
-// pointer.  Only the code from pkt4_receive is shown here.
+// pointer.  Only the code from "pkt4_receive" is shown here.
 
 int pkt4_receive(CalloutHandle& handle) {
     // Retrieve the pointer to the SecurityInformation object
@@ -881,7 +882,7 @@ int pkt4_receive(CalloutHandle& handle) {
 }
 
 // No context_destroy callout is needed to delete the allocated
-// SecurityInformation object.  When the CalloutHandle is destroyed, the shared
+// SecurityInformation object.  When the @c CalloutHandle is destroyed, the shared
 // pointer object will be destroyed.  If that is the last shared pointer to the
 // allocated memory, then it too will be deleted.
 @endcode
@@ -915,13 +916,13 @@ registration is through the LibraryHandle object.  This was briefly
 introduced in the discussion of the framework functions, in that
 an object of this type is pass to the "load" function.  A LibraryHandle
 can also be obtained from within a callout by calling the CalloutHandle's
-getLibraryHandle() method.
+@c getLibraryHandle() method.
 
 The LibraryHandle provides three methods to manipulate callouts:
 
-- registerCallout - register a callout on a hook.
-- deregisterCallout - deregister a callout from a hook.
-- deregisterAllCallouts - deregister all callouts on a hook.
+- @c registerCallout - register a callout on a hook.
+- @c deregisterCallout - deregister a callout from a hook.
+- @c deregisterAllCallouts - deregister all callouts on a hook.
 
 The following sections cover some of the ways in which these can be used.
 
@@ -960,7 +961,7 @@ a hook point.  Although it is likely to be rare for user code to need to
 do this, there may be instances where it make sense.
 
 To register multiple callouts on a hook, just call
-LibraryHandle::registerCallout multiple times on the same hook, e.g.
+@c LibraryHandle::registerCallout multiple times on the same hook, e.g.
 
 @code
     libhandle.registerCallout("pkt4_receive", classify);
@@ -968,7 +969,7 @@ LibraryHandle::registerCallout multiple times on the same hook, e.g.
 @endcode
 
 The hooks framework will call the callouts in the order they are
-registered.  The same CalloutHandle is passed between them, so any
+registered.  The same @c CalloutHandle is passed between them, so any
 change made to the CalloutHandle's arguments, "skip" flag, or per-request
 context by the first is visible to the second.
 
@@ -1036,7 +1037,7 @@ int write_data(CalloutHandle& handle) {
     flush(interesting);
 
     // We've logged the data, so deregister ourself.  This callout will not
-    // be called again until it is registered by pkt4_receive.
+    // be called again until it is registered by "pkt4_receive".
 
     handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data);
 
@@ -1093,7 +1094,7 @@ request.
 
 The vertical blue lines represent callout context. Context is
 per-packet but also per-library.  When the server calls "authorize",
-the CalloutHandle's getContext and setContext methods access a context
+the CalloutHandle's @c getContext and @c setContext methods access a context
 created purely for library 1. The next callout on the hook will access
 context created for library 2. These contexts are passed to the callouts
 associated with the next hook.  So when "check" is called, it gets the
@@ -1132,7 +1133,7 @@ as separate elements of the hooks-libraries configuration element, e.g.
 
 In rare cases, it is possible that one library may want to pass
 data to another.  This can be done in a limited way by means of the
-CalloutHandle's setArgument and getArgument calls.  For example, in the
+CalloutHandle's @c setArgument and @c getArgument calls.  For example, in the
 above diagram, the callout "add_option" can pass a value to "putopt"
 by setting a name.value pair in the hook's argument list.  "putopt"
 would be able to read this, but would not be able to return information
@@ -1185,7 +1186,7 @@ to add one.) For example:
 extern "C" {
 
 int version() {
-    return (BIND10_HOOKS_VERSION);
+    return (KEA_HOOKS_VERSION);
 }
 
 int load() {

src/lib/log/logging.dox

@@ -583,10 +583,8 @@ configuration. As soon as any specification is processed (even an
 empty one), the buffered log messages will be flushed according to
 the specification. Note that if this option is used, the program
 SHOULD call one of the @ref isc::log::LoggerManager::process() calls.
-(If you are using the built-in logging configuration handling in @ref
-isc::config::ModuleCCSession, this is automatically handled.) If the
-program exits before this is done, all log messages are dumped in a raw
-format to stdout (so that no messages get lost).</dd>
+If the program exits before this is done, all log messages are dumped
+in a raw format to stdout (so that no messages get lost).</dd>
 </dl>
 
 @subsubsection logInitializationCppVariant2 Variant #2, Used by Unit Tests
@@ -648,12 +646,12 @@ specified in the hook library when the library is loaded. Conversely, the
 messages have to be removed from the dictionary when the library is unloaded.
 
 The new messages are added to the global dictionary using the
-@c isc::log::MessageInitializer::loadDictionary static function. It is
-called by the @c isc::hooks::LibraryManager::loadLibrary for each loaded
+@ref isc::log::MessageInitializer::loadDictionary static function. It is
+called by the @ref isc::hooks::LibraryManager::loadLibrary for each loaded
 library.
 
 When the library is unloaded, the instance of the
-@c isc::log::MessageInitializer defined in the library is destroyed
+@ref isc::log::MessageInitializer defined in the library is destroyed
 and its destructor removes the messages registered by the destroyed
 instance from the global dictionary.
 

src/lib/util/optional_value.h

@@ -107,7 +107,7 @@ public:
     ///
     /// It does not alter the actual value. It only marks it "specified" or
     /// "unspecified".
-    /// @param specified boolean that determined if a value is specified or not
+    /// @param state determines if a value is specified or not
     void specify(const OptionalValueState& state) {
         specified_ = state.specified_;
     }