documentation

1 files changed, 45 insertions, 4 deletions

diff --git a/lib/model.py b/lib/model.py
index 348c541..e0ce056 100644
--- a/lib/model.py
+++ b/lib/model.py
@@ -1158,9 +1158,22 @@ class PTAModel:
 
 
 class KConfigModel:
-    """Model for a specific system attribute such as ROM or RAM usage"""
+    """Decision-Tree Model for a specific system attribute such as ROM or RAM usage"""
+
+    class Node:
+        pass
+
+    class Leaf(Node):
+        """
+        A Leaf node describes system behaviour for a set of configurations which are
+        similar enough to warrant no additional decomposition.
+
+        :param value: A model value, e.g. expected ROM or RAM usage in Byte
+        :type value: float
+        :param stddev: Standard deviation of benchmark data used to generate this leaf node
+        :type stddev: float
+        """
 
-    class Leaf:
         def __init__(self, value, stddev):
             self.value = value
             self.stddev = stddev
@@ -1179,7 +1192,21 @@ class KConfigModel:
         def to_json(self):
             return {"value": self.value, "stddev": self.stddev}
 
-    class BoolNode:
+    class BoolNode(Node):
+        """
+        A Bool node describes a single boolean Kconfig variable.
+
+        It holds two children: one for the tree in which the variable is enabled (y), and one for the tree in which it is disabled (n). A tree may be None, e.g.
+        if there were no matching configurations during model generation or if the configuration described by the path from root to the child is illegal.
+
+        :param symbol: Kconfig symbol name
+        :type symbol: str
+        :param child_n: sub-tree for symbol == n (disabled)
+        :type child_n: class:`KConigModel.Node`, optional
+        :param child_y: sub-tree for symbol == y (enabled)
+        :type child_y: class:`KConigModel.Node`, optional
+        """
+
         def __init__(self, symbol):
             self.symbol = symbol
             self.child_n = None
@@ -1222,7 +1249,19 @@ class KConfigModel:
                 ret["y"] = None
             return ret
 
-    class ChoiceNode:
+    class ChoiceNode(Node):
+        """
+        A Choice node describes a single mandatory Kconfig choice.
+
+        It holds one sub-tree for each choice variable. As the choice is mandatory, a valid configuration must select exactly one of them.
+        The sub-tree for a choice variable corresponds to configurations in which it is enabled (set to y).
+
+        :param symbol: Kconfig choice name
+        :type symbol: str
+        :param choice: map of symbol name -> class:`Node` object
+        :type choce: dict
+        """
+
         def __init__(self, symbol):
             self.symbol = symbol
             self.choice = dict()
@@ -1283,6 +1322,7 @@ class KConfigModel:
         self = cls()
         self.attribute = json_input["attribute"]
         self.symbols = json_input["symbols"]
+        self.choices = json_input["choices"]
         self.model = self._node_from_json(json_input["model"])
         return self
 
@@ -1317,6 +1357,7 @@ class KConfigModel:
         output = {
             "model": self.model.to_json(),
             "symbols": self.symbols,
+            "choices": self.choices,
             "attribute": self.attribute,
         }
         return output