Add some commends based on code review

scripts/py_matter_idl/matter_idl/data_model_xml/handlers/parsing.py

@@ -93,7 +93,16 @@ def NormalizeName(name: str) -> str:
     while '__' in name:
         name = name.replace('__', '_')
 
-    # TODO: should we handle acronyms in some way?
+    # NOTE: zapt generators for IDL files use a construct of the form
+    #       `{{asUpperCamelCase name preserveAcronyms=true}}`
+    #       and it is somewhat unclear what preserveAcronyms will do.
+    #
+    #      Current assumption is that spec already has acronyms set in
+    #      the correct place and at least for some basic tests this method
+    #      generates good names
+    #
+    #      If any acronyms seem off in naming at some point, more logic may
+    #      be needed here.
 
     # At this point, we remove all _ and make sure _ is followed by an uppercase
     while name.endswith('_'):

scripts/py_matter_idl/matter_idl/data_model_xml_parser.py

@@ -54,6 +54,15 @@ def normalize_order(idl: Idl):
        output is easily diffed by humans
     """
 
+    # This method exists because `zapt` generation of IDL files
+    # are generally based on SQL select query ordering, likely
+    # with some sort fields to achieve determinism
+    #
+    # However overall, especially if manual editing, it seems
+    # easier to just fix a sort order instead of trying to
+    # match another tool ordering that resides in another
+    # code location.
+
     idl.clusters.sort(key=lambda c: c.name)
 
     for cluster in idl.clusters: