Update Comments

- Add TODO items for missing options
- Add missing toolchain managed options commented out
- Homogenise Headings and block comments

CMakeLists.txt

@@ -59,7 +59,7 @@ if( GODOT_ENABLE_TESTING )
     add_subdirectory( test )
 endif()
 
-# If this is the top level CMakeLists.txt, Generators which honor the
+#[[ If this is the top level CMakeLists.txt, Generators which honor the
-# USE_FOLDERS flag will organize godot-cpp targets under the subfolder
+USE_FOLDERS flag will organize godot-cpp targets under the subfolder
-# 'godot-cpp'. This is enable by default from CMake version 3.26
+'godot-cpp'. This is enable by default from CMake version 3.26 ]]
 set_property(GLOBAL PROPERTY USE_FOLDERS ON)

cmake/android.cmake

@@ -25,10 +25,21 @@ Android platforms.
 There is further information and examples in the doc/cmake.rst file.
 
 ]=======================================================================]
+
+#[============================[ Android Options ]============================]
 function( android_options )
-    # Android Options
+    #[[ The options present in the SCons build shown below are managed by
+    toolchain files, further information can be found in doc/cmake.rst
+
+    android_api_level : Target Android API level.
+        Default = 21
+
+    ANDROID_HOME : Path to your Android SDK installation.
+        Default = os.environ.get("ANDROID_HOME", os.environ.get("ANDROID_SDK_ROOT")
+    ]]
 endfunction()
 
+#[===========================[ Target Generation ]===========================]
 function( android_generate )
     target_compile_definitions(${TARGET_NAME}
             PUBLIC

cmake/common_compiler_flags.cmake

@@ -8,7 +8,7 @@ features. For target platform specific flags look to each of the
 ``cmake/<platform>.cmake`` files.
 
 The default compile and link options CMake adds can be found in the
-platform modules_. When a project is created it initialises its variables from
+platform modules_. When a project is created it initializes its variables from
 the ``CMAKE_*`` values. The cleanest way I have found to alter these defaults
 is the use of the ``CMAKE_PROJECT_<PROJECT-NAME>_INCLUDE`` as demonstrated by
 the emsdkHack.cmake to overcome the limitation on shared library creation.
@@ -35,6 +35,7 @@ set( GT_V11 "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,11>" )
 set( LT_V11 "$<VERSION_LESS:$<CXX_COMPILER_VERSION>,11>" )
 set( GE_V12 "$<VERSION_GREATER_EQUAL:$<CXX_COMPILER_VERSION>,12>" )
 
+#[===========================[ compiler_detection ]===========================]
 #[[ Check for clang-cl with MSVC frontend
 The compiler is tested and set when the project command is called.
 The variable CXX_COMPILER_FRONTEND_VARIANT was introduced in 3.14
@@ -54,6 +55,9 @@ function( compiler_detection )
     endif ()
 endfunction(  )
 
+#[=========================[ common_compiler_flags ]=========================]
+#[[ This function assumes it is being called from within one of the platform
+generate functions, with all the variables from lower scopes defined. ]]
 function( common_compiler_flags )
 
     # These compiler options reflect what is in godot/SConstruct.

cmake/emsdkHack.cmake

@@ -31,7 +31,7 @@ if( EMSCRIPTEN )
     set(CMAKE_STRIP FALSE)  # used by default in pybind11 on .so modules
 
     # The Emscripten toolchain sets the default value for EMSCRIPTEN_SYSTEM_PROCESSOR to x86
-    # and CMAKE_SYSTEM_PROCESSOR to this value. I don't want that.
+    # and copies that to CMAKE_SYSTEM_PROCESSOR. We dont want that.
     set(CMAKE_SYSTEM_PROCESSOR "wasm32" )
     # the above prevents the need for logic like:
     #if( ${CMAKE_SYSTEM_NAME} STREQUAL Emscripten )

cmake/godotcpp.cmake

@@ -11,18 +11,12 @@ This if statement simply silences that warning.
 if( CMAKE_C_COMPILER )
 endif ()
 
-#[=======================================================================[.rst:
+#[[ Include Platform Files
-Include Platform Files
+Because these files are included into the top level CMakeLists.txt before the
-----------------------
-
-Because these files are included into the top level CMakelists.txt before the
 project directive, it means that
 
-* ``CMAKE_CURRENT_SOURCE_DIR`` is the location of godot-cpp's CMakeLists.txt
+CMAKE_CURRENT_SOURCE_DIR is the location of godot-cpp's CMakeLists.txt
-* ``CMAKE_SOURCE_DIR`` is the location where any prior ``project(...)``
+CMAKE_SOURCE_DIR is the location where any prior project() directive was ]]
-  directive was
-
-]=======================================================================]
 include( ${CMAKE_CURRENT_SOURCE_DIR}/cmake/common_compiler_flags.cmake)
 include( ${CMAKE_CURRENT_SOURCE_DIR}/cmake/android.cmake)
 include( ${CMAKE_CURRENT_SOURCE_DIR}/cmake/ios.cmake)
@@ -43,7 +37,8 @@ set( PLATFORM_LIST linux macos windows android ios web )
 # List of known architectures
 set( ARCH_LIST universal x86_32 x86_64 arm32 arm64 rv64 ppc32 ppc64 wasm32 )
 
-# Function to map processors to known architectures
+#[=============================[ godot_arch_map ]=============================]
+#[[ Function to map CMAKE_SYSTEM_PROCESSOR names to godot arch equivalents ]]
 function( godot_arch_map ALIAS PROC )
     string( TOLOWER "${PROC}" PROC )
 
@@ -157,7 +152,7 @@ function( godotcpp_options )
     windows_options()
 endfunction()
 
-# Function to configure and generate the targets
+#[===========================[ Target Generation ]===========================]
 function( godotcpp_generate )
     #[[ Multi-Threaded MSVC Compilation
     When using the MSVC compiler the build command -j <n> only specifies

cmake/ios.cmake

@@ -6,10 +6,20 @@ This file contains functions for options and configuration for targeting the
 Ios platform
 
 ]=======================================================================]
+
+#[==============================[ iOS Options ]==============================]
 function(ios_options)
-    # iOS options
+#    TODO "ios_simulator", "Target iOS Simulator", False
+#    TODO "ios_min_version", "Target minimum iphoneos/iphonesimulator version", "12.0"
+#    TODO "IOS_TOOLCHAIN_PATH",
+#        "Path to iOS toolchain",
+#        "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain",
+#    TODO "IOS_SDK_PATH", "Path to the iOS SDK", ""
+#
+#    TODO if has_ios_osxcross(): "ios_triple", "Triple for ios toolchain", ""
 endfunction()
 
+#[===========================[ Target Generation ]===========================]
 function(ios_generate)
     target_compile_definitions(${TARGET_NAME}
             PUBLIC

cmake/linux.cmake

@@ -6,10 +6,18 @@ This file contains functions for options and configuration for targeting the
 Linux platform
 
 ]=======================================================================]
+
+#[=============================[ Linux Options ]=============================]
 function( linux_options )
-    # Linux Options
+    #[[ The options present in the SCons build shown below are managed by
+    toolchain files, further information can be found in doc/cmake.rst
+
+    use_llvm : Use the LLVM compiler
+        Default: False
+]]
 endfunction()
 
+#[===========================[ Target Generation ]===========================]
 function( linux_generate )
     target_compile_definitions( ${TARGET_NAME}
             PUBLIC

cmake/macos.cmake

@@ -7,6 +7,7 @@ MacOS platform
 
 ]=======================================================================]
 
+#[===========================[ Find Dependencies ]===========================]
 # APPLE is set to True when the target system is an Apple platform
 # (macOS, iOS, tvOS, visionOS or watchOS).
 if( APPLE )
@@ -18,12 +19,14 @@ if( APPLE )
         NO_DEFAULT_PATH )
 endif( APPLE )
 
+#[=============================[ MacOS Options ]=============================]
 function( macos_options )
     # TODO "macos_deployment_target" "macOS deployment target" "default"
     # TODO "macos_sdk_path" "macOS SDK path" ""
     # TODO if has_osxcross(): "osxcross_sdk" "OSXCross SDK version" "darwin16"
 endfunction()
 
+#[===========================[ Target Generation ]===========================]
 function( macos_generate )
 
     # OSX_ARCHITECTURES does not support generator expressions.

cmake/web.cmake

@@ -10,11 +10,12 @@ Web platform
 # Emscripten requires this hack for use of the SHARED option
 set( CMAKE_PROJECT_godot-cpp_INCLUDE cmake/emsdkHack.cmake )
 
+#[==============================[ Web Options ]==============================]
 function( web_options )
     # web options
 endfunction()
 
-
+#[===========================[ Target Generation ]===========================]
 function( web_generate )
     target_compile_definitions(${TARGET_NAME}
             PUBLIC

cmake/windows.cmake

@@ -37,6 +37,8 @@ that dependent targets rely on it, and point them to these comments as to why.
 .. https://discourse.cmake.org/t/mt-staticrelease-doesnt-match-value-md-dynamicrelease/5428/4
 
 ]=======================================================================]
+
+# FIXME INVALID LOGIC: consumers may also have not called project() yet.
 if( PROJECT_NAME ) # we are not the top level if this is true
     if( DEFINED CMAKE_MSVC_RUNTIME_LIBRARY )
         # Warning that we are clobbering the variable.
@@ -55,6 +57,20 @@ function( windows_options )
 
     option( GODOT_DEBUG_CRT "Compile with MSVC's debug CRT (/MDd)" OFF )
 
+    # NOT PLANNED:  silence_msvc : Silence MSVC's cl/link stdout bloat, redirecting errors to stderr. Default = True
+
+    #[[ The options present in the SCons build shown below are managed by
+    toolchain files, further information can be found in doc/cmake.rst
+
+    use_mingw : Use the MinGW compiler instead of MSVC
+        Default = False
+
+    mingw_prefix : MinGW prefix
+        Default = os.getenv("MINGW_PREFIX", "")
+
+    use_llvm : Use the LLVM compiler
+        Default = False
+    ]]
 endfunction()
 
 #[===========================[ Target Generation ]===========================]