Linting and correcting comments

Author: theotherjimmy

tools/test/config/config_test.py

@@ -1,6 +1,6 @@
 """
 mbed SDK
-Copyright (c) 2011-2016 ARM Limited
+Copyright (c) 2011-2017 ARM Limited
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -27,8 +27,12 @@
 from tools.targets import set_targets_json_location, Target, TARGET_NAMES
 from tools.config import ConfigException, Config
 
-# Compare the output of config against a dictionary of known good results
 def compare_config(cfg, expected):
+    """Compare the output of config against a dictionary of known good results
+
+    :param cfg: the configuration to check
+    :param expected: what to expect in that config
+    """
     try:
         for k in cfg:
             if cfg[k].value != expected[k]:
@@ -41,16 +45,28 @@ def compare_config(cfg, expected):
     return ""
 
 def data_path(path):
+    """The expected data file for a particular test
+
+    :param path: the path to the test
+    """
     return join(path, "test_data.json")
 
 def is_test(path):
+    """Does a directory represent a test?
+
+    :param path: the path to the test
+    """
     return isfile(data_path(path))
 
 root_dir = abspath(dirname(__file__))
 
 @pytest.mark.parametrize("name", filter(lambda d: is_test(join(root_dir, d)),
-                                             os.listdir(root_dir)))
+                                        os.listdir(root_dir)))
 def test_config(name):
+    """Run a particular configuration test
+
+    :param name: test name (same as directory name)
+    """
     test_dir = join(root_dir, name)
     test_data = json.load(open(data_path(test_dir)))
     targets_json = os.path.join(test_dir, "targets.json")
@@ -81,9 +97,7 @@ def test_init_app_config(target):
     """
     Test that the initialisation correctly uses app_config
 
-    :param mock_json_file_to_dict: mock of function json_file_to_dict
-    :param _: mock of function _process_config_and_overrides (not tested)
-    :return:
+    :param target: The target to use
     """
     set_targets_json_location()
     with patch.object(Config, '_process_config_and_overrides'),\
@@ -103,9 +117,7 @@ def test_init_no_app_config(target):
     """
     Test that the initialisation works without app config
 
-    :param mock_json_file_to_dict: mock of function json_file_to_dict
-    :param _: patch of function _process_config_and_overrides (not tested)
-    :return:
+    :param target: The target to use
     """
     set_targets_json_location()
     with patch.object(Config, '_process_config_and_overrides'),\
@@ -122,9 +134,7 @@ def test_init_no_app_config_with_dir(target):
     Test that the initialisation works without app config and with a
     specified top level directory
 
-    :param mock_json_file_to_dict: mock of function json_file_to_dict
-    :param _: patch of function _process_config_and_overrides (not tested)
-    :return:
+    :param target: The target to use
     """
     set_targets_json_location()
     with patch.object(Config, '_process_config_and_overrides'),\
@@ -149,9 +159,7 @@ def test_init_override_app_config(target):
     Test that the initialisation uses app_config instead of top_level_dir
     when both are specified
 
-    :param mock_json_file_to_dict: mock of function json_file_to_dict
-    :param _: patch of function _process_config_and_overrides (not tested)
-    :return:
+    :param target: The target to use
     """
     set_targets_json_location()
     with patch.object(Config, '_process_config_and_overrides'),\

tools/test/memap/memap_test.py

@@ -1,6 +1,6 @@
 """
 mbed SDK
-Copyright (c) 2016 ARM Limited
+Copyright (c) 2017 ARM Limited
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.
@@ -60,7 +60,7 @@ def memap_parser():
             ".flash_config":0,
             "unknown":0,
             "OUTPUT":0,
-            },
+        },
         "[lib]/libc.a/lib_a-printf.o": {
             ".text": 4,
             ".data": 5,
@@ -84,7 +84,7 @@ def memap_parser():
             ".flash_config":0,
             "unknown":0,
             "OUTPUT":0,
-            },
+        },
         "main.o": {
             ".text": 7,
             ".data": 8,
@@ -108,7 +108,7 @@ def memap_parser():
             ".flash_config":0,
             "unknown":0,
             "OUTPUT":0,
-            },
+        },
         "test.o": {
             ".text": 0,
             ".data": 0,
@@ -132,7 +132,7 @@ def memap_parser():
             ".flash_config":0,
             "unknown":0,
             "OUTPUT":0,
-            },
+        },
     }
     return memap_parser
 
@@ -142,8 +142,10 @@ def generate_test_helper(memap_parser, format, depth, file_output=None):
     Helper that tests that the member variables "modules" is
     unchanged after calling "generate_output"
 
-    :param output_type: type string that is passed to "generate_output"
-    :param file_output: path to output file that is passed to "generate_output"
+    :param memap_parser: the parser object
+    :param depth: how much detail to put in the report
+    :param format:  the file type to output
+    :param file_output: the file to output to
     """
 
     old_modules = deepcopy(memap_parser.modules)
@@ -158,6 +160,9 @@ def generate_test_helper(memap_parser, format, depth, file_output=None):
 def test_report_computed(memap_parser, depth):
     """
     Test that a report and summary are computed
+
+    :param memap_parser: Mocked parser
+    :param depth: the detail of the output
     """
 
     memap_parser.generate_output('table', depth)
@@ -171,6 +176,8 @@ def test_report_computed(memap_parser, depth):
 def test_generate_output_table(memap_parser, depth):
     """
     Test that an output of type "table" can be generated correctly
+    :param memap_parser: Mocked parser
+    :param depth: the detail of the output
     """
     generate_test_helper(memap_parser, 'table', depth)
 
@@ -179,8 +186,11 @@ def test_generate_output_table(memap_parser, depth):
 def test_generate_output_json(memap_parser, tmpdir, depth):
     """
     Test that an output of type "json" can be generated correctly
+    :param memap_parser: Mocked parser
+    :param tmpdir: a unique location to place an output file
+    :param depth: the detail of the output
     """
-    file_name = str(tmpdir.join('json_test_output.json').realpath())
+    file_name = str(tmpdir.join('output.json').realpath())
     generate_test_helper(memap_parser, 'json', depth, file_name)
     assert isfile(file_name), "Failed to create json file"
     json.load(open(file_name))
@@ -191,8 +201,10 @@ def test_generate_output_csv_ci(memap_parser, tmpdir, depth):
     """
     Test ensures that an output of type "csv-ci" can be generated correctly
 
-    :return:
+    :param memap_parser: Mocked parser
+    :param tmpdir: a unique location to place an output file
+    :param depth: the detail of the output
     """
-    file_name = str(tmpdir.join('.csv_ci_test_output.csv').realpath())
+    file_name = str(tmpdir.join('output.csv').realpath())
     generate_test_helper(memap_parser, 'csv-ci', depth, file_name)
     assert isfile(file_name), "Failed to create csv-ci file"

tools/test/targets/target_test.py

@@ -39,7 +39,10 @@ def test_device_name():
 
 @contextmanager
 def temp_target_file(extra_target, json_filename='custom_targets.json'):
-    """Create an extra targets temp file in a context manager"""
+    """Create an extra targets temp file in a context manager
+
+    :param extra_target: the contents of the extra targets temp file
+    """
     tempdir = tempfile.mkdtemp()
     try:
         targetfile = os.path.join(tempdir, json_filename)
@@ -67,7 +70,7 @@ def test_add_extra_targets():
 
         assert 'Test_Target' in TARGET_MAP
         assert TARGET_MAP['Test_Target'].core is None, \
-                "attributes should be inherited from Target"
+            "attributes should be inherited from Target"
 
 def test_modify_existing_target():
     """Set default targets file, then override base Target definition"""

tools/test/test_api/test_api_test.py

@@ -42,9 +42,10 @@ def test_find_tests_app_config(base_dir, target, toolchain_name, app_config):
     """
     Test find_tests for correct use of app_config
 
-    :param mock_prepare_toolchain: mock of function prepare_toolchain
-    :param mock_scan_resources: mock of function scan_resources
-    :return:
+    :param base_dir: dummy value for the test base directory
+    :param target: the target to "test" for
+    :param toolchain_name: the toolchain to use for "testing"
+    :param app_config: Application configuration parameter to find tests
     """
     set_targets_json_location()
     with patch('tools.test_api.scan_resources') as mock_scan_resources,\
@@ -68,9 +69,10 @@ def test_find_tests_app_config(build_path, target, toolchain_name, app_config):
     """
     Test find_tests for correct use of app_config
 
-    :param mock_prepare_toolchain: mock of function prepare_toolchain
-    :param mock_scan_resources: mock of function scan_resources
-    :return:
+    :param base_dir: dummy value for the test base directory
+    :param target: the target to "test" for
+    :param toolchain_name: the toolchain to use for "testing"
+    :param app_config: Application configuration parameter to find tests
     """
     tests = {'test1': 'test1_path','test2': 'test2_path'}
     src_paths = ['.']