[3259] Update documentation with new syntax

doc/guide/hooks.xml

@@ -53,18 +53,29 @@
 <userinput>"Dhcp4": {
     :
     "hooks-libraries": [
-       "/opt/charging.so",
-       "/opt/local/notification.so"
+        {
+            "library": "/opt/charging.so"
+        },
+        {
+            "library": "/opt/local/notification.so"
+        }
     ]
     :
 }</userinput>
 </screen>
       </para>
       <note><para>
-      At present, the libraries are specified as a simple list.  A future
-      version of Kea will support the capability of specifying a set of
-      parameters for each library. When that is added, it is likely
-      that the syntax for specifying hooks libraries will change.
+        This is a change to the syntax used in Kea 0.9.2 and earlier, where
+        hooks-libraries was a list of strings, each string being the name of
+        a library.  The change has been made in Kea 1.0 to facilitate the
+        specification of library-specific parameters, a feature that will be
+        added to a future version of Kea.
+      </para>
+      <para>
+        To ease the transtion, the old syntax is still accepted, although a
+        warning message is issued when it is encountered.  Users are urged
+        to switch to the new syntax as the old syntax will be withdrawn when
+        parameters are finally added to Kea.
       </para></note>
       <para>
       Notes:

src/lib/hooks/hooks_user.dox

@@ -792,15 +792,30 @@ DHCPv4 module, it must be listed in the "hooks-libraries" element of the
 @code
 "Dhcp4": {
        :
-    "hooks-libraries": [ "/usr/local/lib/example.so" ]
+    "hooks-libraries": [
+        {
+            "library": "/usr/local/lib/example.so"
+        },
+        {
+            :
+        }
        :
 }
 @endcode
 (Note that "hooks" is plural.)
 
+Each entry in the "hooks-libraries" list is a structure (a "map" in JSON
+parlance) that holds the following element:
+- library - the name of the library to load.  This must be a string.
+
 The DHCPv4 server will load the library and execute the callouts each time a
 request is received.
 
+@note The syntax of the hooks-libraries configuration element has changed
+since kea 0.9.2 (in that version, "hooks-libraries" was just a list of
+libraries).  This change is in preparation for the introduction of
+library-=specific parameters, which will be added to Kea in a version after 1.0.
+
 @note The above assumes that the hooks library will be used with a version of
 Kea that is dynamically-linked.  For information regarding running
 hooks libraries against a statically-linked Kea, see
@@ -1184,8 +1199,15 @@ as separate elements of the hooks-libraries configuration element, e.g.
 @code
 "Dhcp4": {
        :
-    "hooks-libraries": [ "/usr/lib/library1.so", "/opt/library2.so" ]
+    "hooks-libraries": [
+        {
+            "library": "/usr/lib/library1.so"
+        },
+        {
+            "library": "/opt/library2.so"
+        }
        :
+    ]
 }
 @endcode