[vcpkg docs] Check for documentation generation in CI (#14614)

* [vcpkg docs] Change how documenting port functions works

Instead of using `##`, use comment blocks for documentation.

Also, add some minor docs and change RST -> MD
so we actually get docs generated.

* add CI stuff

* regenerate docs

* fix vcpkg_find_acquire_program to not use _execute_process

23 files changed, 222 insertions, 64 deletions

diff --git a/docs/maintainers/execute_process.md b/docs/maintainers/execute_process.md
index bafb1e57c..b7d57110c 100644
--- a/docs/maintainers/execute_process.md
+++ b/docs/maintainers/execute_process.md
@@ -5,6 +5,5 @@ is enabled.
 
 In order to execute a process in Download Mode call `vcpkg_execute_in_download_mode()` instead.
 
-
 ## Source
 [scripts/cmake/execute_process.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/execute_process.cmake)

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index 943afa6e7..56e42bbd8 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -1,4 +1,4 @@
-<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->
+<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->
 
 # Portfile helper functions

 - [execute\_process](execute_process.md)

@@ -11,6 +11,8 @@
 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)

 - [vcpkg\_build\_ninja](vcpkg_build_ninja.md)

 - [vcpkg\_build\_nmake](vcpkg_build_nmake.md)

+- [vcpkg\_build\_qmake](vcpkg_build_qmake.md)

+- [vcpkg\_buildpath\_length\_warning](vcpkg_buildpath_length_warning.md)

 - [vcpkg\_check\_features](vcpkg_check_features.md)

 - [vcpkg\_check\_linkage](vcpkg_check_linkage.md)

 - [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)

@@ -20,6 +22,7 @@
 - [vcpkg\_configure\_gn](vcpkg_configure_gn.md)

 - [vcpkg\_configure\_make](vcpkg_configure_make.md)

 - [vcpkg\_configure\_meson](vcpkg_configure_meson.md)

+- [vcpkg\_configure\_qmake](vcpkg_configure_qmake.md)

 - [vcpkg\_copy\_pdbs](vcpkg_copy_pdbs.md)

 - [vcpkg\_copy\_tool\_dependencies](vcpkg_copy_tool_dependencies.md)

 - [vcpkg\_copy\_tools](vcpkg_copy_tools.md)

@@ -27,6 +30,7 @@
 - [vcpkg\_execute\_build\_process](vcpkg_execute_build_process.md)

 - [vcpkg\_execute\_in\_download\_mode](vcpkg_execute_in_download_mode.md)

 - [vcpkg\_execute\_required\_process](vcpkg_execute_required_process.md)

+- [vcpkg\_execute\_required\_process\_repeat](vcpkg_execute_required_process_repeat.md)

 - [vcpkg\_extract\_source\_archive](vcpkg_extract_source_archive.md)

 - [vcpkg\_extract\_source\_archive\_ex](vcpkg_extract_source_archive_ex.md)

 - [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)

@@ -39,6 +43,8 @@
 - [vcpkg\_from\_github](vcpkg_from_github.md)

 - [vcpkg\_from\_gitlab](vcpkg_from_gitlab.md)

 - [vcpkg\_from\_sourceforge](vcpkg_from_sourceforge.md)

+- [vcpkg\_get\_program\_files\_platform\_bitness](vcpkg_get_program_files_platform_bitness.md)

+- [vcpkg\_get\_windows\_sdk](vcpkg_get_windows_sdk.md)

 - [vcpkg\_install\_cmake](vcpkg_install_cmake.md)

 - [vcpkg\_install\_gn](vcpkg_install_gn.md)

 - [vcpkg\_install\_make](vcpkg_install_make.md)

@@ -48,3 +54,4 @@
 - [vcpkg\_install\_qmake](vcpkg_install_qmake.md)

 - [vcpkg\_internal\_get\_cmake\_vars](vcpkg_internal_get_cmake_vars.md)

 - [vcpkg\_prettify\_command](vcpkg_prettify_command.md)

+- [vcpkg\_replace\_string](vcpkg_replace_string.md)

diff --git a/docs/maintainers/vcpkg_add_to_path.md b/docs/maintainers/vcpkg_add_to_path.md
index b47d86cef..0c8986276 100644
--- a/docs/maintainers/vcpkg_add_to_path.md
+++ b/docs/maintainers/vcpkg_add_to_path.md
@@ -21,6 +21,5 @@ The default is to append.
 * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
-
 ## Source
 [scripts/cmake/vcpkg_add_to_path.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_add_to_path.cmake)

diff --git a/docs/maintainers/vcpkg_build_make.md b/docs/maintainers/vcpkg_build_make.md
index de44a84d4..5c7037b68 100644
--- a/docs/maintainers/vcpkg_build_make.md
+++ b/docs/maintainers/vcpkg_build_make.md
@@ -6,7 +6,7 @@ Build a linux makefile project.
 ```cmake
 vcpkg_build_make([BUILD_TARGET <target>]
                  [ADD_BIN_TO_PATH]
-                 [ENABLE_INSTALL])
+                 [ENABLE_INSTALL]
                  [MAKEFILE <makefileName>]
                  [LOGFILE_ROOT <logfileroot>])
 ```
@@ -36,7 +36,7 @@ Additional subdir to invoke make in. Useful if only parts of a port should be bu
 
 ## Notes:
 This command should be preceeded by a call to [`vcpkg_configure_make()`](vcpkg_configure_make.md).
-You can use the alias [`vcpkg_install_make()`](vcpkg_configure_make.md) function if your CMake script supports the
+You can use the alias [`vcpkg_install_make()`](vcpkg_install_make.md) function if your CMake script supports the
 "install" target
 
 ## Examples
diff --git a/docs/maintainers/vcpkg_build_nmake.md b/docs/maintainers/vcpkg_build_nmake.md
index 1daa0717f..337269eeb 100644
--- a/docs/maintainers/vcpkg_build_nmake.md
+++ b/docs/maintainers/vcpkg_build_nmake.md
@@ -64,7 +64,7 @@ Adds the appropriate Release and Debug `bin\` directories to the path during the
 
 ## Notes:
 This command should be preceeded by a call to [`vcpkg_configure_nmake()`](vcpkg_configure_nmake.md).
-You can use the alias [`vcpkg_install_nmake()`](vcpkg_configure_nmake.md) function if your CMake script supports the
+You can use the alias [`vcpkg_install_nmake()`](vcpkg_install_nmake.md) function if your CMake script supports the
 "install" target
 
 ## Examples
diff --git a/docs/maintainers/vcpkg_build_qmake.md b/docs/maintainers/vcpkg_build_qmake.md
new file mode 100644
index 000000000..2dab94176
--- /dev/null
+++ b/docs/maintainers/vcpkg_build_qmake.md
@@ -0,0 +1,10 @@
+# vcpkg_build_qmake
+
+Build a qmake-based project, previously configured using vcpkg_configure_qmake.
+
+```cmake
+vcpkg_build_qmake()
+```
+
+## Source
+[scripts/cmake/vcpkg_build_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_build_qmake.cmake)

diff --git a/docs/maintainers/vcpkg_buildpath_length_warning.md b/docs/maintainers/vcpkg_buildpath_length_warning.md
new file mode 100644
index 000000000..d766afc9d
--- /dev/null
+++ b/docs/maintainers/vcpkg_buildpath_length_warning.md
@@ -0,0 +1,11 @@
+# vcpkg_buildpath_length_warning
+
+Warns the user if their vcpkg installation path might be too long for the package they're installing.
+
+## Usage
+```cmake
+vcpkg_buildpath_length_warning(13)
+```
+
+## Source
+[scripts/cmake/vcpkg_buildpath_length_warning.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_buildpath_length_warning.cmake)

diff --git a/docs/maintainers/vcpkg_check_features.md b/docs/maintainers/vcpkg_check_features.md
index cec01dde2..fcf313bfd 100644
--- a/docs/maintainers/vcpkg_check_features.md
+++ b/docs/maintainers/vcpkg_check_features.md
@@ -143,6 +143,5 @@ vcpkg_configure_cmake(
 * [pcl](https://github.com/microsoft/vcpkg/blob/master/ports/pcl/portfile.cmake)
 * [rocksdb](https://github.com/microsoft/vcpkg/blob/master/ports/rocksdb/portfile.cmake)
 
-
 ## Source
 [scripts/cmake/vcpkg_check_features.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_features.cmake)

diff --git a/docs/maintainers/vcpkg_check_linkage.md b/docs/maintainers/vcpkg_check_linkage.md
index 406325dba..f9c149b68 100644
--- a/docs/maintainers/vcpkg_check_linkage.md
+++ b/docs/maintainers/vcpkg_check_linkage.md
@@ -28,7 +28,7 @@ This command will either alter the settings for `VCPKG_LIBRARY_LINKAGE` or fail,
 
 ## Examples
 
-* [libimobiledevice](https://github.com/Microsoft/vcpkg/blob/master/ports/libimobiledevice/portfile.cmake)
+* [abseil](https://github.com/Microsoft/vcpkg/blob/master/ports/abseil/portfile.cmake)
 
 ## Source
 [scripts/cmake/vcpkg_check_linkage.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_check_linkage.cmake)

diff --git a/docs/maintainers/vcpkg_common_definitions.md b/docs/maintainers/vcpkg_common_definitions.md
index 9bbc64b1e..10e765f1e 100644
--- a/docs/maintainers/vcpkg_common_definitions.md
+++ b/docs/maintainers/vcpkg_common_definitions.md
@@ -24,6 +24,5 @@ CMAKE_STATIC_LIBRARY_(PREFIX|SUFFIX), CMAKE_SHARED_LIBRARY_(PREFIX|SUFFIX) and C
 Furthermore the variables CMAKE_FIND_LIBRARY_(PREFIXES|SUFFIXES) are also defined for the target so that
 portfiles are able to use find_library calls to discover dependent libraries within the current triplet for ports.
 
-
 ## Source
 [scripts/cmake/vcpkg_common_definitions.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_common_definitions.cmake)

diff --git a/docs/maintainers/vcpkg_configure_qmake.md b/docs/maintainers/vcpkg_configure_qmake.md
new file mode 100644
index 000000000..5117600df
--- /dev/null
+++ b/docs/maintainers/vcpkg_configure_qmake.md
@@ -0,0 +1,21 @@
+# vcpkg_configure_qmake
+
+Configure a qmake-based project.
+
+```cmake
+vcpkg_configure_qmake(
+    SOURCE_PATH <pro_file_path>
+    [OPTIONS arg1 [arg2 ...]]
+    [OPTIONS_RELEASE arg1 [arg2 ...]]
+    [OPTIONS_DEBUG arg1 [arg2 ...]]
+)
+```
+
+### SOURCE_PATH
+The path to the *.pro qmake project file.
+
+### OPTIONS, OPTIONS\_RELEASE, OPTIONS\_DEBUG
+The options passed to qmake.
+
+## Source
+[scripts/cmake/vcpkg_configure_qmake.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_qmake.cmake)

diff --git a/docs/maintainers/vcpkg_execute_in_download_mode.md b/docs/maintainers/vcpkg_execute_in_download_mode.md
index 0a7f8a8f7..51fa46420 100644
--- a/docs/maintainers/vcpkg_execute_in_download_mode.md
+++ b/docs/maintainers/vcpkg_execute_in_download_mode.md
@@ -5,25 +5,30 @@ Execute a process even in download mode.
 ## Usage
 ```cmake
 vcpkg_execute_in_download_mode(
-    COMMAND <cmd> [<arguments>...]
-    OUTPUT_QUIET ERROR_QUIET OUTPUT_STRIP_TRAILING_WHITESPACE ERROR_STRIP_TRAILING_WHITESPACE
-    WORKING_DIRECTORY <dir>
-    TIMEOUT <seconds>
-    RESULT_VARIABLE <seconds>
-    OUTPUT_VARIABLE <var_out>
-    ERROR_VARIABLE <var_err>
-    INPUT_FILE <f_in>
-    OUTPUT_FILE <f_out>
-    ERROR_FILE <f_err>
-    ENCODING <enc>
+    COMMAND <cmd> [<arguments>]
+    [WORKING_DIRECTORY <dir>]
+    [TIMEOUT <seconds>]
+    [RESULT_VARIABLE <variable>]
+    [OUTPUT_VARIABLE <variable>]
+    [ERROR_VARIABLE <variable>]
+    [INPUT_FILE <file>]
+    [OUTPUT_FILE <file>]
+    [ERROR_FILE <file>]
+    [OUTPUT_QUIET]
+    [ERROR_QUIET]
+    [OUTPUT_STRIP_TRAILING_WHITESPACE]
+    [ERROR_STRIP_TRAILING_WHITESPACE]
+    [ENCODING <name>]
 )
 ```
 
-The signature of this function is identical with `execute_process()` except that
+The signature of this function is identical to `execute_process()` except that
 it only accepts one COMMAND argument, i.e., does not support chaining multiple
 commands with pipes.
 
-See `execute_process()` for a detailed description of the parameters.
+See [`execute_process()`] for a detailed description of the parameters.
+
+[`execute_process()`]: https://cmake.org/cmake/help/latest/command/execute_process.html
 
 ## Source
 [scripts/cmake/vcpkg_execute_in_download_mode.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_in_download_mode.cmake)

diff --git a/docs/maintainers/vcpkg_execute_required_process_repeat.md b/docs/maintainers/vcpkg_execute_required_process_repeat.md
new file mode 100644
index 000000000..09102ca1a
--- /dev/null
+++ b/docs/maintainers/vcpkg_execute_required_process_repeat.md
@@ -0,0 +1,16 @@
+# vcpkg_execute_required_process_repeat
+
+Execute a process until the command succeeds, or until the COUNT is reached.
+
+## Usage
+```cmake
+vcpkg_execute_required_process_repeat(
+    COUNT <num>
+    COMMAND <cmd> [<arguments>]
+    WORKING_DIRECTORY <directory>
+    LOGNAME <name>
+)
+```
+
+## Source
+[scripts/cmake/vcpkg_execute_required_process_repeat.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_execute_required_process_repeat.cmake)

diff --git a/docs/maintainers/vcpkg_extract_source_archive.md b/docs/maintainers/vcpkg_extract_source_archive.md
index 4971df960..895dd16fc 100644
--- a/docs/maintainers/vcpkg_extract_source_archive.md
+++ b/docs/maintainers/vcpkg_extract_source_archive.md
@@ -15,7 +15,7 @@ The full path to the archive to be extracted.
 This is usually obtained from calling [`vcpkg_download_distfile`](vcpkg_download_distfile.md).
 
 ### TARGET_DIRECTORY
-If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}\src\`.
+If specified, the archive will be extracted into the target directory instead of `${CURRENT_BUILDTREES_DIR}/src/`.
 
 This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
 
diff --git a/docs/maintainers/vcpkg_find_acquire_program.md b/docs/maintainers/vcpkg_find_acquire_program.md
index aef499b12..ed93ba2ca 100644
--- a/docs/maintainers/vcpkg_find_acquire_program.md
+++ b/docs/maintainers/vcpkg_find_acquire_program.md
@@ -13,29 +13,29 @@ This variable specifies both the program to be acquired as well as the out param
 ## Notes
 The current list of programs includes:
 
-- 7Z
-- ARIA2 (Downloader)
-- BISON
-- CLANG
-- DARK
-- DOXYGEN
-- FLEX
-- GASPREPROCESSOR
-- GPERF
-- PERL
-- PYTHON2
-- PYTHON3
-- GIT
-- GN
-- GO
-- JOM
-- MESON
-- NASM
-- NINJA
-- NUGET
-- SCONS
-- SWIG
-- YASM
+* 7Z
+* ARIA2 (Downloader)
+* BISON
+* CLANG
+* DARK
+* DOXYGEN
+* FLEX
+* GASPREPROCESSOR
+* GPERF
+* PERL
+* PYTHON2
+* PYTHON3
+* GIT
+* GN
+* GO
+* JOM
+* MESON
+* NASM
+* NINJA
+* NUGET
+* SCONS
+* SWIG
+* YASM
 
 Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
 
diff --git a/docs/maintainers/vcpkg_find_fortran.md b/docs/maintainers/vcpkg_find_fortran.md
index eb04ebdf3..4ee10b163 100644
--- a/docs/maintainers/vcpkg_find_fortran.md
+++ b/docs/maintainers/vcpkg_find_fortran.md
@@ -6,8 +6,7 @@ Windows(x86/x64) Only: If not it will switch/enable MinGW gfortran
 
 ## Usage
 ```cmake
-vcpkg_find_fortran(<additional_cmake_args_out>
-)
+vcpkg_find_fortran(<additional_cmake_args_out>)
 ```
 
 ## Source
diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md
index 18e8d0867..5a0b2d644 100644
--- a/docs/maintainers/vcpkg_fixup_cmake_targets.md
+++ b/docs/maintainers/vcpkg_fixup_cmake_targets.md
@@ -27,6 +27,11 @@ By default the parent directory of CONFIG_PATH is removed if it is named "cmake"
 Passing this option disable such behavior, as it is convenient for ports that install
 more than one CMake package configuration file.
 
+### NO_PREFIX_CORRECTION
+Disables the correction of_IMPORT_PREFIX done by vcpkg due to moving the targets.
+Currently the correction does not take into account how the files are moved and applies
+I rather simply correction which in some cases will yield the wrong results.
+
 ## Notes
 Transform all `/debug/<CONFIG_PATH>/*targets-debug.cmake` files and move them to `/<TARGET_PATH>`.
 Removes all `/debug/<CONFIG_PATH>/*targets.cmake` and `/debug/<CONFIG_PATH>/*config.cmake`.
diff --git a/docs/maintainers/vcpkg_fixup_pkgconfig.md b/docs/maintainers/vcpkg_fixup_pkgconfig.md
index be77ae347..48870e972 100644
--- a/docs/maintainers/vcpkg_fixup_pkgconfig.md
+++ b/docs/maintainers/vcpkg_fixup_pkgconfig.md
@@ -36,7 +36,7 @@ Skips the library checks in vcpkg_fixup_pkgconfig. Only use if the script itself
 Still work in progress. If there are more cases which can be handled here feel free to add them
 
 ## Examples
-Just call vcpkg_fixup_pkgconfig() after any install step which installs *.pc files.
+Just call `vcpkg_fixup_pkgconfig()` after any install step which installs *.pc files.
 
 ## Source
 [scripts/cmake/vcpkg_fixup_pkgconfig.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_fixup_pkgconfig.cmake)

diff --git a/docs/maintainers/vcpkg_from_gitlab.md b/docs/maintainers/vcpkg_from_gitlab.md
index fe75ecf93..ceef6f2d4 100644
--- a/docs/maintainers/vcpkg_from_gitlab.md
+++ b/docs/maintainers/vcpkg_from_gitlab.md
@@ -61,6 +61,5 @@ This exports the `VCPKG_HEAD_VERSION` variable during head builds.
 * [folly](https://github.com/Microsoft/vcpkg/blob/master/ports/folly/portfile.cmake#L15)
 * [z3](https://github.com/Microsoft/vcpkg/blob/master/ports/z3/portfile.cmake#L13)
 
-
 ## Source
 [scripts/cmake/vcpkg_from_gitlab.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_from_gitlab.cmake)

diff --git a/docs/maintainers/vcpkg_get_program_files_platform_bitness.md b/docs/maintainers/vcpkg_get_program_files_platform_bitness.md
new file mode 100644
index 000000000..a39992f4e
--- /dev/null
+++ b/docs/maintainers/vcpkg_get_program_files_platform_bitness.md
@@ -0,0 +1,13 @@
+# vcpkg_get_program_files_platform_bitness
+
+Get the Program Files directory of the current platform's bitness:
+either `$ENV{ProgramW6432}` on 64-bit windows,
+or `$ENV{PROGRAMFILES}` on 32-bit windows.
+
+## Usage:
+```cmake
+vcpkg_get_program_files_platform_bitness(<variable>)
+```
+
+## Source
+[scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_program_files_platform_bitness.cmake)

diff --git a/docs/maintainers/vcpkg_get_windows_sdk.md b/docs/maintainers/vcpkg_get_windows_sdk.md
new file mode 100644
index 000000000..b32f3f49d
--- /dev/null
+++ b/docs/maintainers/vcpkg_get_windows_sdk.md
@@ -0,0 +1,11 @@
+# vcpkg_get_windows_sdk
+
+Get the Windows SDK number.
+
+## Usage:
+```cmake
+vcpkg_get_windows_sdk(<variable>)
+```
+
+## Source
+[scripts/cmake/vcpkg_get_windows_sdk.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_get_windows_sdk.cmake)

diff --git a/docs/maintainers/vcpkg_replace_string.md b/docs/maintainers/vcpkg_replace_string.md
new file mode 100644
index 000000000..5e04d0368
--- /dev/null
+++ b/docs/maintainers/vcpkg_replace_string.md
@@ -0,0 +1,11 @@
+# vcpkg_replace_string
+
+Replace a string in a file.
+
+```cmake
+vcpkg_replace_string(filename match_string replace_string)
+```
+
+
+## Source
+[scripts/cmake/vcpkg_replace_string.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_replace_string.cmake)

diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1
index abb91af61..c984ad77b 100644
--- a/docs/regenerate.ps1
+++ b/docs/regenerate.ps1
@@ -1,27 +1,81 @@
-Param([string]$VcpkgRoot = "")
+[CmdletBinding()]
+Param(
+    [String]$VcpkgRoot = ''
+)
 
-$ErrorActionPreference = "Stop"
-
-if (!$VcpkgRoot) {
-    $VcpkgRoot = ".."
+if ([String]::IsNullOrEmpty($VcpkgRoot)) {
+    $VcpkgRoot = "${PSScriptRoot}/.."
 }
 
 $VcpkgRoot = Resolve-Path $VcpkgRoot
 
-if (!(Test-Path "$VcpkgRoot\.vcpkg-root")) {
+if (-not (Test-Path "$VcpkgRoot/.vcpkg-root")) {
     throw "Invalid vcpkg instance, did you forget -VcpkgRoot?"
 }
 
-Set-Content -Path "$PSScriptRoot\maintainers\portfile-functions.md" -Value "<!-- Run regenerate.ps1 to extract documentation from scripts\cmake\*.cmake -->`n`n# Portfile helper functions"
+Set-Content `
+    -Path "$PSScriptRoot/maintainers/portfile-functions.md" `
+    -Value "<!-- Run regenerate.ps1 to extract documentation from scripts/cmake/*.cmake -->`n`n# Portfile helper functions"
+
+Get-ChildItem "$VcpkgRoot/scripts/cmake" -Filter '*.cmake' | ForEach-Object {
+    $filename = $_
+    [String[]]$contents = Get-Content $filename
+
+    if ($contents[0] -eq '# DEPRECATED') {
+        return
+    }
+
+    [String]$startCommentRegex = '#\[(=*)\['
+    [String]$endCommentRegex = ''
+    [Bool]$inComment = $False
+    [Bool]$failThisFile = $False
+
+    $contents = $contents | ForEach-Object {
+        if (-not $inComment) {
+            if ($_ -match "^\s*${startCommentRegex}(\.[a-z]*)?:?\s*$") {
+                if (-not [String]::IsNullOrEmpty($matches[2]) -and $matches[2] -ne '.md') {
+                    Write-Warning "The documentation in ${filename} doesn't seem to be markdown (extension: $($matches[2])). Only markdown is supported; please rewrite the documentation in markdown."
+                }
+                $inComment = $True
+                $endCommentRegex = "\]$($matches[1])\]"
+            } elseif ($_ -match $startCommentRegex) {
+                $failThisFile = $True
+                Write-Warning "Invalid start of comment -- the comment start must be at the beginning of the line.
+    (on line: `"$_`")"
+            } else {
+                # do nothing -- we're outside a comment, so cmake code
+            }
+        } else {
+            if ($_ -match "^\s*#?${endCommentRegex}\s*$") {
+                $inComment = $False
+                $endCommentRegex = ''
+            } elseif ($_ -match $endCommentRegex) {
+                $failThisFile = $True
+                Write-Warning "Invalid end of comment -- the comment end must be on it's own on a line.
+    (on line: `"$_`")"
+            } else {
+                # regular documentation line
+                $_
+            }
+        }
+    }
+
+    if ($inComment) {
+        Write-Warning "File ${filename} has an unclosed comment."
+        return
+    }
+
+    if ($failThisFile) {
+        return
+    }
 
-ls "$VcpkgRoot\scripts\cmake\*.cmake" | % {
-    $contents = Get-Content $_ `
-    | ? { $_ -match "^## |^##`$" } `
-    | % { $_ -replace "^## ?","" }
 
     if ($contents) {
-        Set-Content -Path "$PSScriptRoot\maintainers\$($_.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($_.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($_.Name))"
-        "- [$($_.BaseName -replace "_","\_")]($($_.BaseName).md)" `
-        | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot\maintainers\portfile-functions.md"
+        Set-Content -Path "$PSScriptRoot/maintainers/$($filename.BaseName).md" -Value "$($contents -join "`n")`n`n## Source`n[scripts/cmake/$($filename.Name)](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/$($filename.Name))"
+        "- [$($filename.BaseName -replace "_","\_")]($($filename.BaseName).md)" `
+        | Out-File -Enc Ascii -Append -FilePath "$PSScriptRoot/maintainers/portfile-functions.md"
+    } elseif (-not $filename.Name.StartsWith("vcpkg_internal")) {
+        # don't worry about undocumented internal functions
+        Write-Warning "The cmake function in file $filename doesn't seem to have any documentation. Make sure the documentation comments are correctly written."
     }
 }