pio: use CCFLAGS for -Werror (#8175)

Also adds some comments referencing SCons documentation

Author: mcspr

tools/platformio-build.py

@@ -22,6 +22,9 @@
 https://arduino.cc/en/Reference/HomePage
 """
 
+# For SCons documentation, see:
+# https://scons.org/doc/latest
+
 # Extends: https://github.com/platformio/platform-espressif8266/blob/develop/builder/main.py
 
 from os.path import isdir, join
@@ -58,16 +61,17 @@ def scons_patched_match_splitext(path, suffixes=None):
 env.Append(
     ASFLAGS=["-x", "assembler-with-cpp"],
 
+    # General options that are passed to the C compiler (C only; not C++)
     CFLAGS=[
         "-std=gnu17",
         "-Wpointer-arith",
         "-Wno-implicit-function-declaration",
-        "-Werror=return-type",
         "-Wl,-EL",
         "-fno-inline-functions",
         "-nostdlib"
     ],
 
+    # General options that are passed to the C and C++ compilers
     CCFLAGS=[
         "-Os",  # optimize for size
         "-mlongcalls",
@@ -78,15 +82,18 @@ def scons_patched_match_splitext(path, suffixes=None):
         "-ffunction-sections",
         "-fdata-sections",
         "-Wall",
+        "-Werror=return-type",
         "-free",
         "-fipa-pta"
     ],
 
+    # General options that are passed to the C++ compiler
     CXXFLAGS=[
         "-fno-rtti",
         "-std=gnu++17"
     ],
 
+    # General user options passed to the linker
     LINKFLAGS=[
         "-Os",
         "-nostdlib",
@@ -105,6 +112,9 @@ def scons_patched_match_splitext(path, suffixes=None):
         "-u", "_UserExceptionVector"
     ],
 
+    # A platform independent specification of C preprocessor definitions as either:
+    # - -DFLAG as "FLAG"
+    # - -DFLAG=VALUE as ("FLAG", "VALUE")
     CPPDEFINES=[
         ("F_CPU", "$BOARD_F_CPU"),
         "__ets__",
@@ -115,18 +125,21 @@ def scons_patched_match_splitext(path, suffixes=None):
         "LWIP_OPEN_SRC"
     ],
 
+    # The list of directories that the C preprocessor will search for include directories
     CPPPATH=[
         join(FRAMEWORK_DIR, "tools", "sdk", "include"),
         join(FRAMEWORK_DIR, "cores", env.BoardConfig().get("build.core")),
         join(platform.get_package_dir("toolchain-xtensa"), "include")
     ],
 
+    # The list of directories that will be searched for libraries
     LIBPATH=[
         join("$BUILD_DIR", "ld"),  # eagle.app.v6.common.ld
         join(FRAMEWORK_DIR, "tools", "sdk", "lib"),
         join(FRAMEWORK_DIR, "tools", "sdk", "ld")
     ],
 
+    # A list of one or more libraries that will be linked with any executable programs created by this environment
     LIBS=[
         "hal", "phy", "pp", "net80211", "wpa", "crypto", "main",
         "wps", "bearssl", "espnow", "smartconfig", "airkiss", "wpa2",