Added more documentation to scripts

tools/extract_function/extract_function.py

@@ -19,6 +19,7 @@ if function_location.endswith('.s'):
 if function_header.endswith(';'):
     function_header = function_header[:-1]
 
+# Extract the function name from the function header argument.
 left_parentheses_index = function_header.find('(')
 if left_parentheses_index >= 0:
     function_name = function_header[function_header.rfind(' ', None, left_parentheses_index) + 1 : left_parentheses_index]
@@ -56,6 +57,7 @@ first_function_start_line = None
 def get_line_address(line: str):
     return line[line.index(ADDRESS_FIND) + len(ADDRESS_FIND) : -1]
 
+# Find the start and end of the function within the ASM file.
 for i, line in enumerate(original_lines):
     if first_function_start_line is None and line.startswith(ARM_FUNC_START):
         first_function_start_line = i
@@ -63,7 +65,7 @@ for i, line in enumerate(original_lines):
         function_start_line = i
     elif line.strip() == f'arm_func_end {function_name}'.strip():
         function_end_line = i
-    
+
     if function_start_line is not None and extract_function_address is None and ADDRESS_FIND in line:
         extract_function_address = get_line_address(line)
     if function_end_line is not None and ADDRESS_FIND in line:
@@ -93,6 +95,7 @@ with open(LSF_FILE_PATH, 'r') as lsf_file:
 
 extract_file_name = f'{file_prefix}{extract_function_address}'
 
+# If needed, add the extracted function's new .o file to main.lsf.
 merge_prev_file = None
 merge_next_file = None
 SRC_LSF_PREFIX = '\tObject src/'
@@ -112,12 +115,15 @@ for i, line in enumerate(lsf_lines):
         if include_new_asm_file:
             lsf_lines[i] += f'\tObject asm/{file_prefix}{new_file_address}.o\n'
         break
-    
+
 BRANCH_LINK_INSTRUCTION = '\tbl '
 BRANCH_LINK_EXCHANGE_INSTRUCTION = '\tblx '
 BRANCH_INSTRUCTION = '\tb '
 WORD_KEY = '.word '
 WORD_PLUS_OFFSET = ' + 0x'
+"""
+Searches through an ASM file's contents for all external symbosl, then populates a .inc file with all the necessary .public definitions.
+"""
 def write_inc_file(lines: List[str], file_path: str):
     defined_functions = set()
     used_functions = set()
@@ -189,6 +195,9 @@ function_body = f"""{function_header}
 
 }}"""
 
+# Add the extracted function to a .h and .c file.
+# If there is an existing C file adjacent to the extracted function, add the function to that file.
+# Otherwise, make a new set of files.
 if merge_prev_file:
     header_file_path = os.path.join(HEADER_FOLDER, f'{merge_prev_file}.h')
     with open(header_file_path, 'r') as header_file:

tools/sync_pmdsky_debug/pmdsky_debug_reader.py

@@ -21,6 +21,9 @@ SYMBOL_BLACKLIST = set([
     'GAME_STATE_VALUES',
 ])
 
+"""
+Returns the file path where pmdsky-debug is located locally, defined within pmdsky_debug_location.txt.
+"""
 def get_pmdsky_debug_location() -> str:
     global pmdsky_debug_path
     if not pmdsky_debug_path:

tools/sync_pmdsky_debug/symbol_details.py

@@ -1,5 +1,7 @@
 from dataclasses import dataclass
 
+# Some symbol names in the decomp do not match pmdsky-debug because of naming convention differences.
+# Map these symbol names between the two projects to avoid changes when syncing the projects.
 MIXED_CASE_SYMBOLS_ARM9 = {
     '_secure': 'SECURE',
     '_start_AutoloadDoneCallback': 'StartAutoloadDoneCallback',

tools/sync_pmdsky_debug/sync_from_pmdsky_debug.py

@@ -16,6 +16,9 @@ pmdsky_debug_symbols = read_pmdsky_debug_symbols()
 xmap_symbols = read_xmap_symbols()
 
 asm_files = []
+"""
+Searches for all files within a directory that have certain extensions.
+"""
 def add_files_with_extensions(folder: str, extensions: List[str]) -> List[str]:
     found_files = []
     for root, _, files in os.walk(folder):
@@ -57,6 +60,8 @@ for language, pmdsky_debug_language_symbols in pmdsky_debug_symbols.items():
 
                 print(f'Replacing {old_symbol.name} with {symbol.name}')
                 replaced_symbols.add(old_symbol.name)
+
+                # Replace symbol occurrences in ASM files.
                 if symbol.is_data:
                     asm_search_string_bases = [
                         f'\n{old_symbol.name}:\n',
@@ -100,6 +105,7 @@ for language, pmdsky_debug_language_symbols in pmdsky_debug_symbols.items():
                     with open(file_path, 'w') as asm_file:
                         asm_file.write(asm_contents)
 
+                # Replace symbol occurrences in C files.
                 src_search_string_data_regex = re.compile(fr'([ &*(]){old_symbol.name}([,); [])')
                 src_search_string_data_regex_replace = fr'\1{symbol.name}\2'
 

tools/sync_pmdsky_debug/sync_to_pmdsky_debug.py

@@ -146,6 +146,7 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma
     symbol_entry_addresses: int | List[int] = symbol_entry_language_addresses[language_key]
 
 
+    # If needed, reorder language addresses within the YAML for consistency with existing pmdsky-debug entries.
     hex_address = HexCapsInt(address)
     reorder_languages = language_key == 'EU' and len(symbol_entry_language_addresses) > 1 and not symbol_entry_language_addresses[language_key]
     if multiple_symbol_suffix.search(symbol.name):
@@ -170,11 +171,14 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma
     if symbol_preexisting:
         return
 
+    # Add the symbol to the correspond header file.
     base_symbol_path = base_symbol_path.replace('.yml', '.h')
     header_path = symbol_path.replace(SYMBOLS_FOLDER, os.path.join('headers', symbol_type_key)).replace('.yml', '.h')
     with open(header_path, 'r') as header_file:
         header_contents = header_file.readlines()
 
+    # Look for the symbol that was immediately before the new symbol in the YAML.
+    # The new symbol will be added directly after this anchor symbol.
     target_line = None
     if symbol_before is not None:
         for i, line in enumerate(header_contents):
@@ -230,6 +234,7 @@ def sync_xmap_symbol(address: int, symbol: SymbolDetails, language: str, yaml_ma
             if f' {base_symbol_name}(' in line:
                 symbol_header = line
                 break
+        # Match the typedefs used in pmdsky-debug.
         symbol_header = symbol_header.replace('u32', 'uint32_t')
         symbol_header = symbol_header.replace('u16', 'uint16_t')
         symbol_header = symbol_header.replace('u8', 'uint8_t')