[2995] Editorial changes to the DHCPv6 hooks documentation.

src/bin/dhcp6/dhcp6_hooks.dox

@@ -18,13 +18,14 @@
  @section dhcpv6HooksIntroduction Introduction
  BIND10 features an API (the "Hooks" API) that allows user-written code to
  be integrated into BIND 10 and called at specific points in its processing.
- An overview of the API and a tutorial for writing generalised hook code can
- API can be found in @ref hooksDevelopersGuide and @ref hooksComponentDeveloperGuide.
+ An overview of the API and a tutorial for writing such code can be found in
+ the @ref hooksDevelopersGuide.  Information for BIND 10 maintainers can be
+ found in the @ref hooksComponentDeveloperGuide.
 
  This manual is more specialised and is aimed at developers of hook
- code for the DHCPv6 server. It describes each hook point, the callouts
- attached to the hook are able to do, and the arguments passed  to them.
- Each entry in this manual has the following information:
+ code for the DHCPv6 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:
 
  - Name of the hook point.
  - Arguments for the callout.  As well as the argument name and data type, the
@@ -36,9 +37,9 @@
      value the callout sends back.  Note that the callout may choose not to
      do any modification, in which case the server will use whatever value
      it sent to the callout.
- - Description: a description of the hook, including where in the processing
-   it is called, a description of the data available, and the possible
-   actions a callout attached to this hook could take.
+ - Description of the hook. This explains where in the processing the hook
+   is located, the possible actions a callout attached to this hook could take,
+   and a description of the data passed to the callouts.
  - Skip flag action: the action taken by the server if a callout chooses to set
     the "skip" flag.
 
@@ -55,18 +56,19 @@ packet processing. Hook points that are not specific to packet processing
 
  - @b Description: this callout is executed when an incoming DHCPv6
    packet is received and its content is parsed. The sole argument -
-   pkt6 - contains a pointer to an isc::dhcp::Pkt6 object that contains all
-   information regarding incoming packet, including its source and
+   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
-   of all options present within and relay information. See Pkt6 class
-   definition for details. All fields of the Pkt6 class can be
-   modified at this time, except data_ (which contains incoming packet
-   as raw buffer, but that information was already parsed, so it
-   doesn't make sense to modify it at this time).
+   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
+   other fields in the Pkt6 object.  For this reason, it doesn't make
+   sense to modify it.)
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
-   drop the packet and will not do anything with it except logging a drop
-   reason if debugging is enabled.
+   drop the packet and start processing the next one.  The reason for the drop
+   will be logged if logging is set to the appropriate debug level.
 
 @subsection dhcpv6HooksSubnet6Select subnet6_select
 
@@ -76,10 +78,10 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection&, direction: <b>in</b>
 
  - @b Description: this callout is executed when a subnet is being
-   selected for incoming packet. All parameters, addresses and
-   prefixes will be assigned from that subnet. Callout can select a
-   different subnet if it wishes so. The list of all subnets currently
-   configured is provided as 'subnet6collection'. The list itself must
+   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
    not be modified.
 
  - <b>Skip flag action</b>: If any callout installed on 'subnet6_select'
@@ -95,17 +97,18 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, 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
-   been inserted into the database. Any modifications made to the
-   Lease6 object will be directly inserted into 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 but it is not inserted into database.  It is
-   possible to distinguish between SOLICIT and REQUEST by checking value
-   of fake_allocation flag: true means that the lease won't be interested
-   into database (SOLICIT), false means that it will (REQUEST).
+   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
+   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>: the "skip" flag is ignored by the server on this
    hook.
@@ -116,19 +119,19 @@ 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 - pkt6 -
-   contains a pointer to Pkt6 class that contains packet, with set
-   source and destination addresses, interface over which it will be
-   send, list of all options and relay information. (See the isc::dhcp::Pkt6
-   class definition for details.) All fields of the Pkt6 class 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 drop this response packet. However, the original
-   request packet from a client was processed, so server's state was likely
-   changed (e.g. lease was allocated). This flag will merely stop the
-   change to be communicated to the client.
+   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 drop this response packet. However, the original request packet
+   from a client was processed, so server's state was most likely changed
+   (e.g. lease was allocated). Setting this flag merely stops the change
+   being communicated to the client.
 
 */