2 files changed, 36 insertions, 31 deletions
diff --git a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md b/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
deleted file mode 100644
index 63218102f..000000000
--- a/docs/maintainers/internal/vcpkg_internal_get_cmake_vars.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# vcpkg_internal_get_cmake_vars
-
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
-
-**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
-Runs a cmake configure with a dummy project to extract certain cmake variables
-
-## Usage
-```cmake
-vcpkg_internal_get_cmake_vars(
-    [OUTPUT_FILE <output_file_with_vars>]
-    [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
-)
-```
-
-## Parameters
-### OPTIONS
-Additional options to pass to the test configure call 
-
-### OUTPUT_FILE
-Variable to return the path to the generated cmake file with the detected `CMAKE_` variables set as `VCKPG_DETECTED_`
-
-## Notes
-If possible avoid usage in portfiles. 
-
-## Examples
-
-* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
-
-## Source
-[scripts/cmake/vcpkg\_internal\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_internal_get_cmake_vars.cmake)
diff --git a/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md b/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md
new file mode 100644
index 000000000..2dcf2a8e7
--- /dev/null
+++ b/docs/maintainers/internal/z_vcpkg_get_cmake_vars.md
@@ -0,0 +1,36 @@
+# z_vcpkg_get_cmake_vars
+
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/).
+
+**Only for internal use in vcpkg helpers. Behavior and arguments will change without notice.**
+Runs a cmake configure with a dummy project to extract certain cmake variables
+
+## Usage
+```cmake
+z_vcpkg_get_cmake_vars(<out-var>)
+```
+
+`z_vcpkg_get_cmake_vars(cmake_vars_file)` sets `<out-var>` to
+a path to a generated CMake file, with the detected `CMAKE_*` variables
+re-exported as `VCPKG_DETECTED_*`.
+
+## Notes
+Avoid usage in portfiles. 
+
+All calls to `z_vcpkg_get_cmake_vars` will result in the same output file;
+the output file is not generated multiple times.
+
+## Examples
+
+* [vcpkg_configure_make](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/vcpkg_configure_make.cmake)
+
+### Basic Usage
+
+```cmake
+z_vcpkg_get_cmake_vars(cmake_vars_file)
+include("${cmake_vars_file}")
+message(STATUS "detected CXX flags: ${VCPKG_DETECTED_CXX_FLAGS}")
+```
+
+## Source
+[scripts/cmake/z\_vcpkg\_get\_cmake\_vars.cmake](https://github.com/Microsoft/vcpkg/blob/master/scripts/cmake/z_vcpkg_get_cmake_vars.cmake)