IMPROVEMENT: annotate_params.py refractor to reduce duplication and i…

…ncrease reuse

MethodicConfigurator/annotate_params.py

@@ -56,6 +56,10 @@ def arg_parser():
                         action='store_true',
                         help='Delete parameter documentation annotations (comments above parameters). Defaults to %(default)s',
                         )
+    parser.add_argument('-f', '--firmware-version',
+                        default='latest',
+                        help='Flight controller firmware version. Defaults to %(default)s.',
+                        )
     parser.add_argument('-s', '--sort',
                         choices=['none', 'missionplanner', 'mavproxy'],
                         default='none',
@@ -646,24 +650,39 @@ def print_read_only_params(doc):
             logging.info(param_name)
 
 
+def annotate_parameters(xml_dir: str, xml_file: str, target: str, vehicle_type: str,  # pylint: disable=too-many-arguments
+                        _firmware_version: str, max_line_length: int, sort: str,
+                        delete_documentation_annotations: bool) -> Dict[str, Any]:
+    """
+    Annotates parameters with documentation fetched from an XML file.
+    """
+    xml_root, param_default_dict = get_xml_data(BASE_URL + vehicle_type + "/", xml_dir, xml_file)
+    doc_dict = create_doc_dict(xml_root, vehicle_type, max_line_length)
+    update_parameter_documentation(doc_dict, target, sort, param_default_dict, delete_documentation_annotations)
+    return doc_dict
+
+
 def main():
     args = arg_parser()
     try:
         xml_dir = args.target if os_path.isdir(args.target) else os_path.dirname(os_path.realpath(args.target))
-        xml_root, param_default_dict = get_xml_data(BASE_URL + args.vehicle_type + "/", xml_dir, PARAM_DEFINITION_XML_FILE)
-        doc_dict = create_doc_dict(xml_root, args.vehicle_type, args.max_line_length)
-        update_parameter_documentation(doc_dict, args.target, args.sort, param_default_dict,
-                                       args.delete_documentation_annotations)
+
+        doc_dict = annotate_parameters(xml_dir, PARAM_DEFINITION_XML_FILE, args.target, args.vehicle_type,
+                                       args.firmware_version, args.max_line_length,
+                                       args.sort, args.delete_documentation_annotations)
         if args.verbose:
             print_read_only_params(doc_dict)
-        if os_path.isfile(os_path.join(os_path.dirname(args.target), LUA_PARAM_DEFINITION_XML_FILE)):
-            xml_root, param_default_dict = get_xml_data(BASE_URL + args.vehicle_type + "/",
-                                                        xml_dir, LUA_PARAM_DEFINITION_XML_FILE)
-            doc_dict = create_doc_dict(xml_root, args.vehicle_type, args.max_line_length)
-            update_parameter_documentation(doc_dict, os_path.join(os_path.dirname(args.target),
-                                                                  "24_inflight_magnetometer_fit_setup.param"),
-                                           args.sort, param_default_dict, args.delete_documentation_annotations)
-    except Exception as exp:  # pylint: disable=W0718
+
+        # Annotate lua MAGfit XML documentation into the respective parameter file
+        xml_file = LUA_PARAM_DEFINITION_XML_FILE
+        target = os_path.join(os_path.dirname(args.target), "24_inflight_magnetometer_fit_setup.param")
+        if os_path.isfile(os_path.join(os_path.dirname(args.target), xml_file)):
+            doc_dict = annotate_parameters(xml_dir, xml_file, target, args.vehicle_type, args.firmware_version,
+                                           args.max_line_length, args.sort, args.delete_documentation_annotations)
+        else:
+            logging.warning("No LUA MAGfit XML documentation found, skipping annotation of %s", target)
+
+    except  (IOError, OSError, SystemExit) as exp:
         logging.fatal(exp)
         sys_exit(1)