[2984] Modified the documentation of some of the hook points

src/bin/dhcp6/dhcp6_hooks.dox

@@ -54,41 +54,41 @@ packet processing. Hook points that are not specific to packet processing
  - @b Arguments:
    - 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 as a raw buffer. The sole argument - query6 -
-   contains a pointer to an isc::dhcp::Pkt6 object that contains raw
-   buffer stored in data_ field. Basic information like protocol,
-   source/destination addresses and ports are set, but the buffer is
-   not parsed yet.  That means that options_ field that will
-   eventually contain a list of objects that represent received
-   options is empty, so all methods that operate on it (e.g.,
-   getOption()) will not work yet. 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 raw bytes data, it is usually
-   better to install your callout on pkt6_receive hook point.
+ - @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
+   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
+   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.
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the
-   server will assume that the callout did parse the buffer and added
-   necessary option objects to the options_ field. Server will not
-   attempt to do the parsing on its own. If the callout sets skip
-   flag, but does not parse the buffer, the server will likely drop
-   the packet due to absence of mandatory options. If you want the
-   packet to be dropped, see skip falg in pkt6_receive hook point.
+   server will assume that the callout parsed the buffer and added then
+   necessary option objects to the 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.
 
  @subsection dhcpv6HooksPkt6Receive pkt6_receive
 
  - @b Arguments:
    - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed when an incoming DHCPv6
+ - @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
    all information regarding incoming packet, including its source and
-   destination addresses, interface over which it was received, a list
+   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_
    contains the incoming packet as raw buffer. By the time this hook is
-   reached, that information has already parsed and is available though
+   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.)
 
@@ -103,7 +103,7 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b subnet6, type: isc::dhcp::Subnet6Ptr, direction: <b>in/out</b>
    - name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection *, direction: <b>in</b>
 
- - @b Description: this callout is executed when a subnet is being
+ - @b Description: This callout is executed when a subnet is being
    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
@@ -122,7 +122,7 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b fake_allocation, type: bool, direction: <b>in</b>
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed after the server engine
+ - @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
@@ -148,30 +148,30 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
    - name: @b ia_na, type: boost::shared_ptr<Option6IA>, direction: <b>in/out</b>
 
- - @b Description: this callout is executed after the server engine is
-   about to renew an existing lease. Client's request is provided as
-   the query6 argument. Existing lease with already modified values is
-   provided in lease6 parameter. The IA_NA option that will be sent
-   back to the client is provided as the ia_na argument. Callouts
-   installed on the lease6_renew may modify content of the
-   lease6. Care should be taken as that modified value will be then
-   applied to the database without any sanity checks. Although
-   envisaged usage assumes modification of T1, T2, preferred and valid
-   lifetimes only, other parameters may be modified as well. The only
-   exception is addr_ field, which must not be modified as it is used
-   by the database to select the existing lease to be updated. Care should
-   be taken to also modify ia_na option to match any changes in the lease6.
+ - @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,
+   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
+   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_
+   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.
    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. unknown, invalid address, invalid iaid
-   renewal attempts will not trigger this hook point.
+   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'
-   sets the skip flag, the server will not renew the lease. It will, however,
-   send back the IA_NA option that looks like if the server did renew
-   the lease. It is recommended to modify ia_na option to reflect the
-   fact that the lease was not updated. Otherwise the client will think
-   that the lease was renewed, but it fact it was not.
+   sets the skip flag, the server will not renew the lease. Under these
+   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.
 
 @subsection dhcpv6HooksLease6Release lease6_release
 
@@ -179,57 +179,60 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b query6, type: isc::dhcp::PktPtr, direction: <b>in</b>
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed after the server engine is
-   about to release an existing lease. Client's request is provided as
-   the query6 argument. Existing lease to be released is
-   provided in lease6 parameter. It doesn't make much sense to modify
-   existing lease6 at this point as it will be destroyed immediately
-   after the callouts conclude their execution.
+ - @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
+   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'
-   sets the skip flag, the server will not delete the lease. However,
-   it will send out the response back to the client as if it did.
+   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.
 
 @subsection dhcpv6HooksPkt6Send pkt6_send
 
  - @b Arguments:
    - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed when server's response
+ - @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
    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, except bufferOut_.
-   (This is scratch space used for constructing the packet after all
-   pkt6_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 assume that the callout did pack transaction-id, mesage type and
-   option objects into bufferOut_ field and will skip packing part.
-   Note that if the callout set skip flag, but did not prepare the
-   output buffer, the server will send zero sized message that will be
+   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.)
+
+ - <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.
+   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 buffer6_send hook point.
+   skip flag in the buffer6_send hook point.
 
 @subsection dhcpv6HooksBuffer6Send buffer6_send
 
  - @b Arguments:
    - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
- - @b Description: this callout is executed when server's response is
+ - @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 destination addresses, interface over which it will be send,
-   list of all options and relay information. All options are already
-   encoded in bufferOut_ field. It doesn't make sense to modify any
-   options at that time as their binary form was already prepared.
-
- - <b>Skip flag action</b>: if any callout sets the skip flag, the server
+   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
+   to modify that data, it will probably be found easier to modify the
+   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
-   from a client was processed, so server's state was most likely changed
+   from a client has been processed, so server's state has most likely changed
    (e.g. lease was allocated). Setting this flag merely stops the change
    being communicated to the client.