Update.py: Tidy up Fn headers, make logger work globally

The function headers have been updated to follow the standard format
that should be being used for tools in mbed. This is a one line summary
followed by a descriptive block with more detail.
Updated the handling of the main function so that the logger becomes
global and thus works across all the functions. This has been tested
with both the fork and branch options, and for levels INFO and DEBUG.

tools/test/examples/update.py

@@ -37,7 +37,8 @@
 
 import os
 from os.path import dirname, abspath, basename
-import sys, logging
+import sys
+import logging
 import argparse
 import json
 import subprocess
@@ -53,7 +54,11 @@ import examples_lib as lib
 from examples_lib import SUPPORTED_TOOLCHAINS
 
 def run_cmd(command, exit_on_failure=False):
-    """ Passes a command to the system and returns a True/False result once the 
+    """ Run a system command and return the result status
+    
+    Description:
+    
+    Passes a command to the system and returns a True/False result, once the 
     command has been executed, indicating success/failure. Commands are passed
     as a list of tokens. 
     E.g. The command 'git remote -v' would be passed in as ['git', 'remote', '-v']
@@ -63,7 +68,7 @@ def run_cmd(command, exit_on_failure=False):
     exit_on_failure - If True exit the program on failure (default = False)
     
     Returns:
-    result - True/False indicating the success/failure of the command
+    return_code - True/False indicating the success/failure of the command
     """
     update_log.debug('[Exec] %s', ' '.join(command))
     return_code = subprocess.call(command, shell=True)
@@ -77,7 +82,11 @@ def run_cmd(command, exit_on_failure=False):
     return return_code
 
 def run_cmd_with_output(command, exit_on_failure=False):
-    """ Passes a command to the system and returns a True/False result once the 
+    """ Run a system command and return the result status plus output  
+    
+    Description:
+        
+    Passes a command to the system and returns a True/False result once the 
     command has been executed, indicating success/failure. If the command was 
     successful then the output from the command is returned to the caller.
     Commands are passed as a list of tokens. 
@@ -88,7 +97,7 @@ def run_cmd_with_output(command, exit_on_failure=False):
     exit_on_failure - If True exit the program on failure (default = False)
     
     Returns:
-    result - True/False indicating the success/failure of the command
+    returncode - True/False indicating the success/failure of the command
     output - The output of the command if it was successful, else empty string
     """
     update_log.debug('[Exec] %s', ' '.join(command))
@@ -117,7 +126,11 @@ def rmtree_readonly(directory):
     shutil.rmtree(directory, onerror=remove_readonly)
 
 def find_all_examples(path):
-    """ Searches the path specified for sub-example folders, ie those containing an
+    """ Search the path for examples
+    
+    Description:
+    
+    Searches the path specified for sub-example folders, ie those containing an
     mbed-os.lib file. If found adds the path to the sub-example to a list which is 
     then returned.
         
@@ -134,7 +147,11 @@ def find_all_examples(path):
     return examples
 
 def upgrade_single_example(example, tag, directory, ref):
-    """ Updates the mbed-os.lib file in the example specified to correspond to the 
+    """ Update the mbed-os version for a single example
+    
+    Description:
+    
+    Updates the mbed-os.lib file in the example specified to correspond to the 
     version specified by the GitHub tag supplied. Also deals with 
     multiple sub-examples in the GitHub repo, updating them in the same way.
         
@@ -191,13 +208,20 @@ def upgrade_single_example(example, tag, directory, ref):
 def prepare_fork(arm_example):
     """ Synchronises a cloned fork to ensure it is up to date with the original. 
 
+    Description:
+    
+    This function sets a fork of an ARMmbed repo to be up to date with the 
+    repo it was forked from. It does this by hard resetting to the ARMmbed
+    master branch.    
+        
     Args:
     arm_example - Full GitHub repo path for original example 
     ret - True if the fork was synchronised successfully, False otherwise
     
     """
 
-    update_log.debug("In: ", os.getcwd())
+    logstr = "In: " + os.getcwd()
+    update_log.debug(logstr)
 
     for cmd in [['git', 'remote', 'add', 'armmbed', arm_example],
                 ['git', 'fetch', 'armmbed'],
@@ -209,6 +233,19 @@ def prepare_fork(arm_example):
     return True
 
 def prepare_branch(branch):
+    """ Set up at branch ready for use in updating examples 
+        
+    Description:
+    
+    This function checks whether or not the supplied branch exists.
+    If it does not, the branch is created and pushed to the origin.
+    The branch is then switched to.
+    
+    Args:
+    arm_example - Full GitHub repo path for original example 
+    ret - True if the fork was synchronised successfully, False otherwise
+    
+    """
 
     update_log.debug("Preparing branch: %s", branch)
 
@@ -237,7 +274,11 @@ def prepare_branch(branch):
     
 def upgrade_example(github, example, tag, ref,
                     user='ARMmbed', branch='master'):
-    """ Clone a version of the example specified and upgrade all versions of 
+    """ Upgrade all versions of mbed-os.lib found in the specified example repo
+    
+    Description:
+    
+    Clone a version of the example specified and upgrade all versions of 
     mbed-os.lib found within its tree.  The version cloned and how it 
     is upgraded depends on the user and branch specified. Only two options 
     are valid:
@@ -257,8 +298,10 @@ def upgrade_example(github, example, tag, ref,
     example - json example object containing the GitHub repo to update.
     tag - GitHub tag corresponding to a version of mbed-os to upgrade to.
     ref - SHA corresponding to the tag
-    user - GitHub user name
+    user - GitHub user name (defaults to 'ARMmbed' if not supplied)
-    branch - branch to update
+    branch - branch to update (defaults to 'master' if not supplied)
+    
+    returns True if the upgrade was successful, False otherwise
     """
                 
     ret = False
@@ -362,21 +405,7 @@ def create_work_directory(path):
     
     os.makedirs(path)
 
-def main(arguments):
+if __name__ == '__main__':
-    """ Will update any mbed-os.lib files found in the example list specified by the config file.
-        If no config file is specified the default 'examples.json' is used. 
-        The update is done by cloning a fork of each example (the fork must be present in the 
-        github account specified by the github user parameter). The fork is searched for any
-        mbed-os.lib files and each one found is updated with the SHA corresponding to the supplied
-        github tag. A pull request is then made from the fork to the original example repo.
-        
-    Args:
-    tag - tag to update the mbed-os.lib to. E.g. mbed-os-5.3.1
-    github_token - Pre-authorised token to allow github access
-    github_user - github username whose account contains the example forks
-    config_file - optional parameter to specify a list of examples
-
-    """
 
     parser = argparse.ArgumentParser(description=__doc__,
                                      formatter_class=argparse.RawDescriptionHelpFormatter)
@@ -391,7 +420,7 @@ def main(arguments):
     exclusive.add_argument('-U', '--github_user', help="GitHub user for forked repos, mutually exclusive to branch option")
     exclusive.add_argument('-b', '--branch', help="Branch to be updated, mutually exclusive to user option")
     
-    args = parser.parse_args(arguments)
+    args = parser.parse_args()
 
     default = getattr(logging, 'INFO')
     level = getattr(logging, args.log_level.upper(), default)
@@ -427,7 +456,7 @@ def main(arguments):
     results = {}
     os.chdir('examples')
 
-    for example in config['examples']:
+    for example in json_data['examples']:
         # Determine if this example should be updated and if so update any found 
         # mbed-os.lib files. 
         
@@ -453,6 +482,3 @@ def main(arguments):
     if failures:
         for fail in failures:
             update_log.info(" FAILED: %s", fail)
-
-if __name__ == '__main__':
-    sys.exit(main(sys.argv[1:]))