From: Tomek Mrugalski <tomasz@isc.org>
Date: Mon, 17 Sep 2018 15:32:20 +0000 (+0200)
Subject: [65-libyang-adaptor] Method descriptions extended.
X-Git-Tag: 30-implement-control-socket-for-ddns_base~1^2~2^2~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6ce51840b1f80a56b4f52d6ad8fbc07227be7e33;p=thirdparty%2Fkea.git

[65-libyang-adaptor] Method descriptions extended.
---

diff --git a/src/lib/yang/adaptor.cc b/src/lib/yang/adaptor.cc
index 96bb3b1b6d..7ed4ad78ca 100644
--- a/src/lib/yang/adaptor.cc
+++ b/src/lib/yang/adaptor.cc
@@ -47,7 +47,7 @@ Adaptor::fromParent(const string& name, ConstElementPtr parent,
         return;
     }
     BOOST_FOREACH(ElementPtr item, list->listValue()) {
-        // don't override?
+        // don't override. Skip this entry if it already has the parameter.
         if (item->contains(name)) {
             continue;
         }
diff --git a/src/lib/yang/adaptor.h b/src/lib/yang/adaptor.h
index f5cb6d5383..8d2089c6a4 100644
--- a/src/lib/yang/adaptor.h
+++ b/src/lib/yang/adaptor.h
@@ -41,12 +41,20 @@ public:
     /// Get user-context and/or comment and return it with the comment
     /// if exists moved inside the user-context (without checking if
     /// there is already a comment as it should never be the case).
+    ///
+    /// This behavior is used to handle comments. For historical purposes
+    /// Kea allows to define comments in some scopes. Once the user-context
+    /// has been introduced, the comment (as a separate text field)
+    /// disappeared and was moved to comment key within user-context.
+    /// Nevertheless, the old syntax is still supported.
     static isc::data::ConstElementPtr
     getContext(isc::data::ConstElementPtr parent);
 
-    /// @brief From parent.
+    /// @brief Moves a parameter from parent to a list of children.
     ///
     /// Move a parameter from the parent to each item in a list.
+    /// If the parameter exists in a child, it is skipped for this
+    /// particular child, not overridden.
     ///
     /// @param name The parameter name.
     /// @param parent The parent element.
@@ -55,9 +63,11 @@ public:
                            isc::data::ConstElementPtr parent,
                            isc::data::ConstElementPtr list);
 
-    /// @brief To parent.
+    /// @brief Moves a parameter to a parent.
     ///
-    /// Move a parameter from children to the parent.
+    /// Move a parameter from children to the parent. All children
+    /// on the list must have the parameter specified and it has to have
+    /// the same value.
     ///
     /// @param name The parameter name.
     /// @param parent The parent element.