[5351] checkpoint: added comment

doc/guide/dhcp4-srv.xml

@@ -4683,6 +4683,9 @@ autogenerated IDs are not stable across configuration changes.</para>
           It should be noted that Kea will not use that information, but will
           simply store and make it available to hook libraries. It is up to the
           hook library to extract that information and make use of it.
+          The parser translates "comment" entries into a user-context
+          with the entry, this allows to attach comments inside the
+          configuration itself.
         </para>
         <para>
           For more background information, see <xref linkend="user-context"/>.

doc/guide/dhcp6-srv.xml

@@ -4650,6 +4650,9 @@ autogenerated IDs are not stable across configuration changes.
           it just stores it, making it available to the hook
           libraries. It is up to each hook library to extract the information
           and make use of it.
+          The parser translates "comment" entries into a user-context
+          with the entry, this allows to attach comments inside the
+          configuration itself.
         </para>
         <para>
           For more background information, see <xref linkend="user-context"/>.

doc/guide/hooks.xml

@@ -2543,6 +2543,14 @@ both the command and the response.
       arbitrary complexity. Kea does not use that data on its own, simply stores
       and makes it available for the hook libraries.
       </para>
+      <para>
+        Usually when an entry is defined multiple times in the same scope
+        the last value is used overwriting previous values (silently:
+        this behavior should be fixed soon). With user contexts values
+        are combined at the first level, for instance multiple user context
+        with a "comment" entry gives an entry with the list of accumulated
+        values.
+      </para>
       <para>
         Another use case for user contexts may be storing comments and other
         information that will be retained by Kea. Regular comments are discarded
@@ -2550,6 +2558,13 @@ both the command and the response.
         useful if you want your comments to survive config-set, config-get
         operations for example.
       </para>
+      <para>
+        The parser translates "comment" entries at locations user context
+        are valid into a user context with a "comment" entry. The pretty
+        print of a configuration does the opposite operation and puts
+        "comment" entries at the beginning of maps as it seems to be the
+        common usage.
+      </para>
       <para>
         As of Kea 1.3, the structures that allow user contexts are pools of all
         types (addresses and prefixes) and subnets. These are supported in both