Clarify

librisworks/src/main/groovy/se/kb/libris/mergeworks/compare/Classification.groovy

@@ -94,9 +94,10 @@ class Classification extends StuffSet {
 
     static sabPrecedes(String a, String b) {
         def (equal, startsWith) = sabPrecedenceRules
-        def startsWithExceptions = ~/^Hcb|^Hdab/
+        // Codes starting with Hcb or Hdab should never be overwritten
+        def overwriteExceptions = ~/^Hcb|^Hdab/
         def preferred = equal[b] ?: startsWith.find { b.startsWith(it.key) }?.value
-        if (preferred && !(a =~ startsWithExceptions)) {
+        if (preferred && !(a =~ overwriteExceptions)) {
             if (preferred['equals'] && a in preferred['equals']) {
                 return true
             }
@@ -108,7 +109,7 @@ class Classification extends StuffSet {
     }
 
     /**
-     * Loads rules for how to merge SAB codes from file into a Map.
+     * Loads rules for how to merge SAB codes from file.
      * The code in the first column is preferred over the other codes in the same row.
      * The codes can contain wildcard characters '?' (anywhere in the string) or '*' (at the end)
      * The asterisk represents any sequence of characters (zero or more)
@@ -120,6 +121,25 @@ class Classification extends StuffSet {
      *  --> Hda.01=c, Hda.016=c, Hda.017=c, Hda.018=c and Hda=c are all picked over over Hda.01, Hda.016, Hda.017, Hda.018 and Hda=c
      * Hcee.03 | Hce.03 | Hcee
      *  --> Hcee.03 is picked over Hce.03 and Hcee
+     *
+     * The rules are loaded into two different maps, 'equal' and 'startsWith'.
+     * The top-level keys of these maps are the codes that can possibly be overwritten.
+     *
+     * In the 'equal' map we can directly look up a code (key) to see if there are preferred codes that should overwrite it,
+     * while in the 'startsWith' map we check if the code starts with any of the keys. For example if the code is 'xyz'
+     * and we have startsWith = ['xx: [:], 'yy': [:] 'xy': [:]] we iterate over the entries until 'xy' is found.
+     *
+     * The value is in turn also a Map containing the codes that are preferred over the code matching the key.
+     * The map at this second level can have two keys, 'equals' and 'startsWith', and the values are sets of preferred codes.
+     *
+     * Example:
+     * [
+     *  'Hc.01': ['equals': ['Hc.01', 'Hc.016', 'Hc.017', 'Hc.018', 'Hcd.01', 'Hcd.016', 'Hcd.017', 'Hcd.018']],
+     *  'Hce': ['startsWith': ['Hce']]
+     * ]
+     *
+     * This means that any code starting with 'Hce' is preferred over just 'Hce' and any of 'Hc.01', 'Hc.016', 'Hc.017'...
+     * is preferred over just 'Hc.01'.
      */
     static Tuple2<Map<String, Map>, Map<String, Map>> loadSabPrecedenceRules() {
         Map equal = [:]