Add documentation

Signed-off-by: Michael Carroll <michael@openrobotics.org>

tools/xmlschema.py

@@ -24,6 +24,8 @@
 from typing import List, Dict, Tuple, Optional
 
 
+# Mapping between "type" values found in SDF files to the corresponding
+# XSD standard datatypes as defined by https://www.w3.org/TR/xmlschema11-2/
 SDF_TYPES_TO_XSD_STD_TYPES = {
     "bool": "boolean",
     "char": "char",
@@ -35,18 +37,21 @@
     "unsigned long": "unsignedLong",
 }
 
+# Mapping between "required" values found in SDF files to the corresponding
+# minOccurs and maxOccurs found in XSD
 SDF_REQUIRED_TO_MIN_MAX_OCCURS: Dict[str, Tuple[str, str]] = {
-    "0": ("0", "1"),
-    "1": ("1", "1"),
-    "+": ("1", "unbounded"),
-    "*": ("0", "unbounded"),
-    "-1": ("0", "unbounded"),
+    "0": ("0", "1"),  # Required: 0,  (minOccurs: 0, maxOccurs: 1)
+    "1": ("1", "1"),  # Required: 1,  (minOccurs: 1, maxOccurs: 1)
+    "+": ("1", "unbounded"),  # Required: +,  (minOccurs: 1, maxOccurs: inf)
+    "*": ("0", "unbounded"),  # Required: *,  (minOccurs: 0, maxOccurs: inf)
+    "-1": ("0", "unbounded"),  # Required: -1, (minOccurs: 0, maxOccurs: inf)
 }
 
 
 def indent_lines(lines: List[str], indent: int) -> List[str]:
     """
-    Indent a group of lines by a set number of spaces
+    Indent a list of xml lines group of lines by a number (indent) of spaces
+
     """
     return [" " * indent + line for line in lines]
 
@@ -60,15 +65,16 @@ def get_attribute(element: ElementTree.Element, attrib: str) -> Optional[str]:
 
 def is_std_type(sdf_type: str) -> bool:
     """
-    Check if sdf_type is a known XSD standard type
+    Check if sdf_type is a known XSD standard type.
+    Return true if the sdf_type is in the set of known types, false otherwise.
     """
     return sdf_type in SDF_TYPES_TO_XSD_STD_TYPES
 
 
 def xsd_type_string(sdf_type: str) -> Optional[str]:
     """
-    If sdf_type is a known XSD standard type, return it.
-    Otherwise, return None
+    Check if xsd_type is a known XSD standard type.
+    If it is, return 'xsd:' + type, None otherwise.
     """
     if is_std_type(sdf_type):
         xsd_type = SDF_TYPES_TO_XSD_STD_TYPES[sdf_type]
@@ -272,9 +278,9 @@ def print_xsd(element: ElementTree.Element, sdf_root_dir: str) -> List[str]:
 
 
 def process(input_file_sdf: str, sdf_dir: str) -> List[str]:
-    '''
+    """
     Produce an XSD file from an input SDF file
-    '''
+    """
     lines = []
     tree = ElementTree.parse(input_file_sdf)
     root = tree.getroot()