[3484] Updated description of hooks for DHCPv4 and DHCPv6 server.

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 been parsed
+   yet. The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4
+   object, which contains the source and destination address of the
+   received packet, 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.
+   the callout will parse 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
+   skip flag in "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 continue using 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/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/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
@@ -831,7 +832,7 @@ 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
@@ -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() {