Update comments

Buildings/Resources/Scripts/travis/templates/BoilerPlant.py

@@ -94,11 +94,7 @@
     ),
 }
 
-# A case is excluded if the "exclusion test" returns true for any of the item value from EXCLUDE.
-# Exclusion test:
-#   - concatenate all class modifications,
-#   - return true if all strings from the item value of EXCLUDE are found in the concatenation product.
-#   - (re patterns are supported: for instance negative lookahead assertion using (?!pattern).)
+# See docstring of `prune_modifications` function for the structure of EXCLUDE.
 EXCLUDE: dict[str, list[list[str]]] = {
     'Buildings.Templates.HeatingPlants.HotWater.Validation.BoilerPlant': [
         [
@@ -108,13 +104,7 @@
     ],
 }
 
-# Class modifications are removed for each model to be simulated according to the following rules.
-# For each item (2-tuple) of the list provided (as value) for each model (key) in REMOVE_MODIF (dict):
-#   - if all patterns of item[0] are found in the original class modifications, and
-#   - if a class modification contains any item within item[1], then it is removed.
-#   - (re patterns are supported: for instance negative lookahead assertion using (?!pattern).)
-# Removing the class modifications this way yields many duplicate sets of class modifications.
-# Those are pruned afterwards.
+# See docstring of `prune_modifications` function for the structure of REMOVE_MODIF.
 REMOVE_MODIF: dict[str, list[tuple[list[str], list[str]]]] = {
     'Buildings.Templates.HeatingPlants.HotWater.Validation.BoilerPlant': [
         (

Buildings/Resources/Scripts/travis/templates/core.py

@@ -218,7 +218,29 @@ def prune_modifications(
     remove_modif: dict[str, list[tuple[list[str], list[str]]]],
     exclude: dict[str, list[list[str]]],
 ) -> None:
-    """Remove class modifications and update tags.
+    """Remove class modifications, and update combination tag.
+
+    A combination is a model and a list of class modifications (and a tag).
+
+    For a given combination:
+        - The `remove_modif` argument is used to exclude a single class modification.
+          Removing class modifications this way yields many duplicate combinations.
+          These duplicates are pruned afterwards.
+        - The `exclude` argument is used to exclude a combination entirely, i.e., all class modifications.
+
+    A class modification is removed from a combination according to the following rules.
+    For each item (2-tuple) of the list provided (as value) for each model (key) in remove_modif (dict):
+    - if all patterns of item[0] are found in the original class modifications of the combination, and
+    - if a class modification contains any item within item[1], then
+    - this class modification is removed.
+    - (re patterns are supported: for instance negative lookahead assertion using (?!pattern).)
+
+    A combination is excluded if the following exclusion test returns true.
+    - Concatenate all class modifications.
+    - Look for the model (key) in exclude (dict).
+    - Iterate over the list of list of class modifications for this model (value of exclude[model]).
+    - For a given list of class modifications , return true if all strings are found in the concatenated class modifications.
+    - (re patterns are supported: for instance negative lookahead assertion using (?!pattern).)
 
     Returns:
         None (modifies inplace)