Started documenting run_other_library_tests.py

generator/tests/test_other_library/run_other_library_tests.py

@@ -20,19 +20,7 @@
 
 
 ##############################################################################
-# Specific generation functions
-
-
-def generate_new_cpp_header(filename, num):
-    ob = common_set_up(filename)
-    working_class = ob['baseElements'][num]
-    if working_class['name'] == gv.document_class:
-        working_class['document'] = True
-    go_into_new_directory()
-    all_files = CppFiles.CppFiles(working_class, True)
-    all_files.write_files()
-    os.chdir('../../.')
-
+# Utility functions
 
 def common_set_up(filename):
     """
@@ -53,7 +41,7 @@ def common_set_up(filename):
 
 def go_into_new_directory():
     """
-    Create the new directory if required. Go into it.
+    Create the new ./temp directory if required. Go into it.
     """
     os.chdir('./temp')
     new_dir = gv.language
@@ -62,7 +50,35 @@ def go_into_new_directory():
     os.chdir(new_dir)
 
 
+##############################################################################
+# Specific generation functions
+
+
+def generate_new_cpp_header(filename, num):
+    """
+    Generate new C++ header and code files.
+
+    :param filename: the XML file to parse.
+    :param num: TODO not too sure about this - it's a list index.
+    :return: nothing
+    """
+    ob = common_set_up(filename)
+    working_class = ob['baseElements'][num]
+    if working_class['name'] == gv.document_class:
+        working_class['document'] = True
+    go_into_new_directory()
+    all_files = CppFiles.CppFiles(working_class, True)
+    all_files.write_files()
+    os.chdir('../../.')
+
+
 def generate_templates(filename):
+    """
+    TODO not sure what this does. Not sure what ValidationFiles class is for.
+
+    :param filename: the XML file to parse.
+    :return: nothing
+    """
     ob = common_set_up(filename)
     gv.populate_error_list(ob)
     ValidationFiles.ValidationFiles(ob, True)
@@ -75,6 +91,12 @@ def generate_templates(filename):
 
 
 def generate_common_templates(filename):
+    """
+    Write the 'common' files. TODO need more explanation.
+
+    :param filename: the XML file to parse.
+    :return: nothing
+    """
     ob = common_set_up(filename)
     gv.populate_error_list(ob)
     go_into_new_directory()
@@ -86,6 +108,12 @@ def generate_common_templates(filename):
 
 
 def generate_forward(filename):
+    """
+    Write extension file with forward declaration of all opaque C types.
+
+    :param filename: the XML file to parse.
+    :return: nothing
+    """
     ob = common_set_up(filename)
     gv.populate_error_list(ob)
     go_into_new_directory()
@@ -96,6 +124,13 @@ def generate_forward(filename):
 
 
 def generate_enum(filename):
+    """
+    According to ExtensionFile.py, this writes the extension types file.
+    TODO what does that mean?
+
+    :param filename: the XML file to parse.
+    :return: nothing
+    """
     ob = common_set_up(filename)
     gv.populate_error_list(ob)
     go_into_new_directory()
@@ -106,6 +141,13 @@ def generate_enum(filename):
 
 
 def generate_binding(filename, binding):
+    """
+    Generate the "binding" files.
+
+    :param filename: the XML file to parse.
+    :param binding: binding to use, e.g. 'swig', 'cmake', 'csharp'
+    :return: nothing
+    """
     ob = common_set_up(filename)
     go_into_new_directory()
 
@@ -119,6 +161,13 @@ def generate_binding(filename, binding):
 
 
 def generate_cmake(filename, binding):
+    """
+    Write CMake files CMakeLists.txt
+
+    :param filename: the XML file to parse.
+    :param binding:
+    :return: nothing
+    """
     ob = common_set_up(filename)
     go_into_new_directory()
 
@@ -139,6 +188,13 @@ def generate_cmake(filename, binding):
 
 
 def generate_global(filename):
+    """
+    Generate the global files required
+    e.g. VERSION.txt, README.md, LICENSE.txt.
+
+    :param filename: the XML file to parse.
+    :return: nothing
+    """
     common_set_up(filename)  # Don't need ob!
     go_into_new_directory()
     generateCode.generate_global_files()
@@ -147,13 +203,28 @@ def generate_global(filename):
 #############################################################################
 # Specific compare functions
 
+
 def compare_files(correct_file, temp_file):
+    """
+    Wrapper function to compare two files: are they identical?
+
+    :param correct_file: the reference file we are comparing against
+    :param temp_file: temporary file generated by the test code.
+    :returns: 0 on success, or file not present; 1 on failure.
+    """
     return test_functions.compare_files(correct_file, temp_file, fails,
                                         not_tested)
 
 #########
 
 def compare_code(class_name, end):
+    """
+    Compare two "code" files. Are they identical?
+
+    :param class_name: name of C++ class used in the test.
+    :param end: file extension, e.g. ".h", ".txt", etc.
+    :returns: 0 on success, or file not present; 1 on failure.
+    """
     correct_file = os.path.normpath('./test-code/{1}/{0}{2}'.format(class_name, gv.language, end))
     temp_file = os.path.normpath('./temp/{1}/{0}{2}'.format(class_name, gv.language, end))
     return compare_files(correct_file, temp_file)
@@ -173,19 +244,26 @@ def compare_code_txt(class_name, ext='.txt'):
 #########
 
 def compare_binding(class_name, binding, end, prefix=""):
+    """
+    Compare two "binding" files.
+
+    :param class_name: C++ class, e.g. "OStream"
+    :param binding: the language binding,e.g. "swig" or "csharp"
+    :param end: file extension, e.g. ".txt", ".cpp"
+    :param prefix: I don't think this is ever used in any function calls.
+    :returns: 0 on success, or file not present; 1 on failure.
+    """
     correct_file = os.path.normpath('./test-code/{2}/{0}/{1}{3}'.format(binding, class_name, gv.language, end))
-    #if prefix:
+    # if prefix:
     temp_file = os.path.normpath('./temp/{3}/{0}/{2}/{1}{4}'.format(binding, class_name, prefix, gv.language, end))
-    #else:
-        #temp_file = os.path.normpath('./temp/{2}/{0}/{1}{3}'.format(binding, class_name, gv.language, end))
+    # else:
+        # temp_file = os.path.normpath('./temp/{2}/{0}/{1}{3}'.format(binding, class_name, gv.language, end))
     return compare_files(correct_file, temp_file)
 
+
 def compare_binding_headers(class_name, binding, prefix):
     return compare_binding(class_name, binding, ".h", prefix)
-# temp/omex/swig/combine/OStream.h=================>> MISSING
-# temp/sedml/swig/sedml/OStream.h=================>> MISSING
-# compare_binding_headers('OStream', binding is swig, prefix is sedml or combine??)
-# present: temp/omex/swig/OStream.h  and  temp/sedml/swig/OStream.h
+
 
 def compare_binding_impl(class_name, binding, prefix):
     return compare_binding(class_name, binding, ".cpp", prefix)
@@ -201,7 +279,6 @@ def compare_binding_file(class_name, binding, prefix):
 def compare_cmake_file(this_dir, prefix):
     correct_file = os.path.normpath('./test-code/{0}/cmake/CMakeLists.txt'.format(gv.language))
     temp_file = os.path.normpath('./temp/{1}/cmake/{0}/CMakeLists.txt'.format(this_dir, gv.language))
-    #temp_file = os.path.normpath('./temp/{0}/cmake/{0}/CMakeLists.txt'.format(gv.language))
     return compare_files(correct_file, temp_file)
 
 #############################################################################
@@ -292,20 +369,20 @@ def test_bindings(name, class_name, test_case, binding, prefix):
     generate_binding(filename, binding)
     fail = 0
     if binding == 'swig':
-        fail += compare_binding_headers('ListWrapper', binding, "") #prefix)
-        fail += compare_binding_headers('OStream', binding, "") #prefix)
-        fail += compare_binding_impl('OStream', binding, "") #prefix)
-        fail += compare_binding_interface('std_set', binding, "") #prefix)
-        fail += compare_binding_headers('lib{0}'.format(prefix), binding, "") #prefix)
-        fail += compare_binding_interface('lib{0}'.format(prefix), binding, "") #prefix)
-        fail += compare_binding_interface('ASTNodes', binding, "") #prefix)
+        fail += compare_binding_headers('ListWrapper', binding, "")
+        fail += compare_binding_headers('OStream', binding, "")
+        fail += compare_binding_impl('OStream', binding, "")
+        fail += compare_binding_interface('std_set', binding, "")
+        fail += compare_binding_headers('lib{0}'.format(prefix), binding, "")
+        fail += compare_binding_interface('lib{0}'.format(prefix), binding, "")
+        fail += compare_binding_interface('ASTNodes', binding, "")
     elif binding == 'csharp':
-        fail += compare_binding_impl('local', binding, "") #prefix)
-        fail += compare_binding_interface('local', binding, "") #prefix)
-        fail += compare_binding_interface('lib{0}'.format(prefix), binding, "") #prefix)
-        fail += compare_binding_file('CMakeLists.txt', binding, "") #prefix)
-        fail += compare_binding_file('compile-native-files.cmake', binding, "") #prefix)
-        fail += compare_binding_file('AssemblyInfo.cs.in', binding, "") #prefix)
+        fail += compare_binding_impl('local', binding, "")
+        fail += compare_binding_interface('local', binding, "")
+        fail += compare_binding_interface('lib{0}'.format(prefix), binding, "")
+        fail += compare_binding_file('CMakeLists.txt', binding, "")
+        fail += compare_binding_file('compile-native-files.cmake', binding, "")
+        fail += compare_binding_file('AssemblyInfo.cs.in', binding, "")
     print('')
     return fail