Appveyor: add comments to the config file

Documentation for 28399, 28454, and previous fixes.

.appveyor.yml

@@ -13,6 +13,7 @@ environment:
   - target: x86_64-w64-mingw32
     compiler_path: mingw64
     mingw_prefix: mingw-w64-x86_64
+    # hardening doesn't work with mingw-w64-x86_64-gcc, because it's gcc 8
     hardening: --disable-gcc-hardening
 
 install:
@@ -28,11 +29,17 @@ install:
     {
         Execute-Command 'c:\msys64\usr\bin\bash' '-e' '-c' $args
     }
+    <# mingw packages start with ${env:mingw_prefix}
+     # unprefixed packages are from MSYS2, which is like Cygwin. Avoid them.
+     #
+     # Use pacman --debug to show package downloads and install locations
+     #>
     Execute-Command "C:\msys64\usr\bin\pacman" -Sy --verbose --needed --noconfirm ${env:mingw_prefix}-libevent ${env:mingw_prefix}-openssl ${env:mingw_prefix}-pkg-config ${env:mingw_prefix}-xz ${env:mingw_prefix}-zstd ;
 
 build_script:
 - ps: >-
     if ($env:compiler -eq "mingw") {
+            <# use the MSYS2 compiler and user binaries to build and install #>
             $oldpath = ${env:Path} -split ';'
             $buildpath = @("C:\msys64\${env:compiler_path}\bin", "C:\msys64\usr\bin") + $oldpath
             $env:Path = @($buildpath) -join ';'
@@ -43,6 +50,10 @@ build_script:
             Set-Location "${env:build}"
             Execute-Bash "which ${env:target}-gcc"
             Execute-Bash "${env:target}-gcc --version"
+            <# compile for mingw
+             # mingw zstd doesn't come with a pkg-config file, so we manually
+             # configure its flags. liblzma just works.
+             #>
             Execute-Bash "ZSTD_CFLAGS='-L/${env:compiler_path}/include' ZSTD_LIBS='-L/${env:compiler_path}/lib -lzstd' ../configure --prefix=/${env:compiler_path} --build=${env:target} --host=${env:target} --disable-asciidoc --enable-fatal-warnings ${env:hardening}"
             Execute-Bash "V=1 make -j2"
             Execute-Bash "V=1 make -j2 install"
@@ -51,6 +62,7 @@ build_script:
 test_script:
 - ps: >-
     if ($env:compiler -eq "mingw") {
+            <# use the MSYS2 compiler binaries to make check #>
             $oldpath = ${env:Path} -split ';'
             $buildpath = @("C:\msys64\${env:compiler_path}\bin") + $oldpath
             $env:Path = $buildpath -join ';'
@@ -61,14 +73,17 @@ test_script:
 on_failure:
 - ps: >-
     if ($env:compiler -eq "mingw") {
+            <# use the MSYS2 user binaries to archive failures #>
             $oldpath = ${env:Path} -split ';'
             $buildpath = @("C:\msys64\usr\bin") + $oldpath
             $env:Path = @($buildpath) -join ';'
             Set-Location "${env:build}"
+            <# store logs as appveyor artifacts: see the artifacts tab #>
             Execute-Bash "7z a logs.zip config.log || true"
             Execute-Bash "7z a logs.zip test-suite.log || true"
             Execute-Bash "appveyor PushArtifact logs.zip || true"
             Execute-Bash "tail -1000 config.log || true"
             Execute-Bash "cat test-suite.log || true"
     }
+# notify the IRC channel of any failures
 - cmd: C:\Python27\python.exe %APPVEYOR_BUILD_FOLDER%\scripts\test\appveyor-irc-notify.py irc.oftc.net:6697 tor-ci failure