Merge pull request #1111 from Microsoft/docs

[vcpkg] Documentation revamp using MkDocs & readthedocs

12 files changed, 413 insertions, 78 deletions

diff --git a/scripts/cmake/vcpkg_acquire_msys.cmake b/scripts/cmake/vcpkg_acquire_msys.cmake
index ee526529b..b63700877 100644
--- a/scripts/cmake/vcpkg_acquire_msys.cmake
+++ b/scripts/cmake/vcpkg_acquire_msys.cmake
@@ -1,3 +1,48 @@
+## # vcpkg_acquire_msys
+##
+## Download and prepare an MSYS2 instance.
+##
+## ## Usage
+## ```cmake
+## vcpkg_acquire_msys(<MSYS_ROOT_VAR>)
+## ```
+##
+## ## Parameters
+## ### MSYS_ROOT_VAR
+## An out-variable that will be set to the path to MSYS2.
+##
+## ## Notes
+## A call to `vcpkg_acquire_msys` will usually be followed by a call to `bash.exe`:
+## ```cmake
+## vcpkg_acquire_msys(MSYS_ROOT)
+## set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
+##
+## vcpkg_execute_required_process(
+##     COMMAND ${BASH} --noprofile --norc "${CMAKE_CURRENT_LIST_DIR}\\build.sh"
+##     WORKING_DIRECTORY ${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-rel
+##     LOGNAME build-${TARGET_TRIPLET}-rel
+## )
+## ```
+## To ensure a package is available:
+## ```cmake
+## vcpkg_acquire_msys(MSYS_ROOT)
+## set(BASH ${MSYS_ROOT}/usr/bin/bash.exe)
+##
+## message(STATUS "Installing MSYS Packages")
+## vcpkg_execute_required_process(
+##     COMMAND
+##         ${BASH} --noprofile --norc -c
+##             "pacman -Sy --noconfirm --needed make"
+##     WORKING_DIRECTORY ${MSYS_ROOT}
+##     LOGNAME pacman-${TARGET_TRIPLET})
+## ```
+##
+## ## Examples
+##
+## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+## * [icu](https://github.com/Microsoft/vcpkg/blob/master/ports/icu/portfile.cmake)
+## * [libvpx](https://github.com/Microsoft/vcpkg/blob/master/ports/libvpx/portfile.cmake)
+
 function(vcpkg_acquire_msys PATH_TO_ROOT_OUT)
   set(TOOLPATH ${DOWNLOADS}/tools/msys2)
 
diff --git a/scripts/cmake/vcpkg_apply_patches.cmake b/scripts/cmake/vcpkg_apply_patches.cmake
index 1ef138a1e..ac6e5cc93 100644
--- a/scripts/cmake/vcpkg_apply_patches.cmake
+++ b/scripts/cmake/vcpkg_apply_patches.cmake
@@ -1,23 +1,35 @@
-#.rst:
-# .. command:: vcpkg_apply_patches
-#
-#  Apply a set of patches to a source tree.
-#
-#  ::
-#  vcpkg_apply_patches(SOURCE_PATH <source_path>
-#                      PATCHES patch1 [patch ...]
-#                      )
-#
-#  ``SOURCE_PATH``
-#    The source path in which apply the patches.
-#  ``PATCHES``
-#    A list of patches that are applied to the source tree
-#  ``QUIET``
-#    If this option is passed, the warning message when applyng
-#    a patch fails is not printed. This is convenient for patches
-#    that are known to fail even on a clean source tree, and for
-#    which the standard warning message would be confusing for the user.
-#
+## # vcpkg_apply_patches
+##
+## Apply a set of patches to a source tree.
+##
+## ## Usage
+## ```cmake
+## vcpkg_apply_patches(
+##     SOURCE_PATH <${SOURCE_PATH}>
+##     [QUIET]
+##     PATCHES <patch1.patch>...
+## )
+## ```
+##
+## ## Parameters
+## ### SOURCE_PATH
+## The source path in which apply the patches. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+##
+## ### PATCHES
+## A list of patches that are applied to the source tree.
+##
+## Generally, these take the form of `${CMAKE_CURRENT_LIST_DIR}/some.patch` to select patches in the `port\<port>\` directory.
+##
+## ### QUIET
+## Disables the warning message upon failure.
+##
+## This should only be used for edge cases, such as patches that are known to fail even on a clean source tree.
+##
+## ## Examples
+##
+## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+## * [freetype](https://github.com/Microsoft/vcpkg/blob/master/ports/freetype/portfile.cmake)
+## * [libpng](https://github.com/Microsoft/vcpkg/blob/master/ports/libpng/portfile.cmake)
 
 function(vcpkg_apply_patches)
     cmake_parse_arguments(_ap "QUIET" "SOURCE_PATH" "PATCHES" ${ARGN})
diff --git a/scripts/cmake/vcpkg_build_msbuild.cmake b/scripts/cmake/vcpkg_build_msbuild.cmake
index 6fe3f5aa0..1e3c85ba2 100644
--- a/scripts/cmake/vcpkg_build_msbuild.cmake
+++ b/scripts/cmake/vcpkg_build_msbuild.cmake
@@ -1,46 +1,59 @@
-#.rst:
-# .. command:: vcpkg_build_msbuild
-#
-#  Build a msbuild-based project.
-#
-#  ::
-#  vcpkg_build_msbuild(PROJECT_PATH <sln_project_path>
-#                      [RELEASE_CONFIGURATION <release_configuration>] # (default = "Release")
-#                      [DEBUG_CONFIGURATION <debug_configuration>] @ (default = "Debug")
-#                      [TARGET_PLATFORM_VERSION <windows_target_platform_version>]
-#                      [PLATFORM <platform>] # (default = "${TRIPLET_SYSTEM_ARCH}")
-#                      [PLATFORM_TOOLSET <platform_toolset>] # (default = "${VCPKG_PLATFORM_TOOLSET}")
-#                      [OPTIONS arg1 [arg2 ...]]
-#                      [OPTIONS_RELEASE arg1 [arg2 ...]]
-#                      [OPTIONS_DEBUG arg1 [arg2 ...]]
-#                      )
-#
-#  ``PROJECT_PATH``
-#    The path to the *.sln msbuild project file.
-#  ``RELEASE_CONFIGURATION``
-#    The configuration (``/p:Configuration`` msbuild parameter)
-#    used for Release builds.
-#  ``DEBUG_CONFIGURATION``
-#    The configuration (``/p:Configuration`` msbuild parameter)
-#    used for Debug builds.
-#  ``TARGET_PLATFORM_VERSION``
-#    The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
-#  ``TARGET``
-#    The MSBuild target to build. (``/t:<TARGET>``)
-#  ``PLATFORM``
-#    The platform (``/p:Platform`` msbuild parameter)
-#    used for the build.
-#  ``PLATFORM_TOOLSET``
-#    The platform toolset (``/p:PlatformToolset`` msbuild parameter)
-#    used for the build.
-#  ``OPTIONS``
-#    The options passed to msbuild for all builds.
-#  ``OPTIONS_RELEASE``
-#    The options passed to msbuild for Release builds.
-#  ``OPTIONS_DEBUG``
-#    The options passed to msbuild for Debug builds.
-#
-
+## # vcpkg_build_msbuild
+##
+## Build an msbuild-based project.
+##
+## ## Usage
+## ```cmake
+## vcpkg_build_msbuild(
+##     PROJECT_PATH <${SOURCE_PATH}/port.sln>
+##     [RELEASE_CONFIGURATION <Release>]
+##     [DEBUG_CONFIGURATION <Debug>]
+##     [TARGET <Build>]
+##     [TARGET_PLATFORM_VERSION <10.0.15063.0>]
+##     [PLATFORM <${TRIPLET_SYSTEM_ARCH}>]
+##     [PLATFORM_TOOLSET <${VCPKG_PLATFORM_TOOLSET}>]
+##     [OPTIONS </p:ZLIB_INCLUDE_PATH=X>...]
+##     [OPTIONS_RELEASE </p:ZLIB_LIB=X>...]
+##     [OPTIONS_DEBUG </p:ZLIB_LIB=X>...]
+## )
+## ```
+##
+## ## Parameters
+## ### PROJECT_PATH
+## The path to the solution (`.sln`) or project (`.vcxproj`) file.
+##
+## ### RELEASE_CONFIGURATION
+## The configuration (``/p:Configuration`` msbuild parameter) used for Release builds.
+##
+## ### DEBUG_CONFIGURATION
+## The configuration (``/p:Configuration`` msbuild parameter)
+## used for Debug builds.
+##
+## ### TARGET_PLATFORM_VERSION
+## The WindowsTargetPlatformVersion (``/p:WindowsTargetPlatformVersion`` msbuild parameter)
+##
+## ### TARGET
+## The MSBuild target to build. (``/t:<TARGET>``)
+##
+## ### PLATFORM
+## The platform (``/p:Platform`` msbuild parameter) used for the build.
+##
+## ### PLATFORM_TOOLSET
+## The platform toolset (``/p:PlatformToolset`` msbuild parameter) used for the build.
+##
+## ### OPTIONS
+## Additional options passed to msbuild for all builds.
+##
+## ### OPTIONS_RELEASE
+## Additional options passed to msbuild for Release builds. These are in addition to `OPTIONS`.
+##
+## ### OPTIONS_DEBUG
+## Additional options passed to msbuild for Debug builds. These are in addition to `OPTIONS`.
+##
+## ## Examples
+##
+## * [libuv](https://github.com/Microsoft/vcpkg/blob/master/ports/libuv/portfile.cmake)
+## * [zeromq](https://github.com/Microsoft/vcpkg/blob/master/ports/zeromq/portfile.cmake)
 
 function(vcpkg_build_msbuild)
     cmake_parse_arguments(_csc "" "PROJECT_PATH;RELEASE_CONFIGURATION;DEBUG_CONFIGURATION;PLATFORM;PLATFORM_TOOLSET;TARGET_PLATFORM_VERSION;TARGET" "OPTIONS;OPTIONS_RELEASE;OPTIONS_DEBUG" ${ARGN})
diff --git a/scripts/cmake/vcpkg_configure_cmake.cmake b/scripts/cmake/vcpkg_configure_cmake.cmake
index cd979be1b..7d43336de 100644
--- a/scripts/cmake/vcpkg_configure_cmake.cmake
+++ b/scripts/cmake/vcpkg_configure_cmake.cmake
@@ -1,3 +1,49 @@
+## # vcpkg_configure_cmake
+##
+## Configure CMake for Debug and Release builds of a project.
+##
+## ## Usage
+## ```cmake
+## vcpkg_configure_cmake(
+##     SOURCE_PATH <${SOURCE_PATH}>
+##     [PREFER_NINJA]
+##     [GENERATOR <"NMake Makefiles">]
+##     [OPTIONS <-DUSE_THIS_IN_ALL_BUILDS=1>...]
+##     [OPTIONS_RELEASE <-DOPTIMIZE=1>...]
+##     [OPTIONS_DEBUG <-DDEBUGGABLE=1>...]
+## )
+## ```
+##
+## ## Parameters
+## ### SOURCE_PATH
+## Specifies the directory containing the `CMakeLists.txt`. By convention, this is usually set in the portfile as the variable `SOURCE_PATH`.
+##
+## ### PREFER_NINJA
+## Indicates that, when available, Vcpkg should use Ninja to perform the build. This should be specified unless the port is known to not work under Ninja.
+##
+## ### GENERATOR
+## Specifies the precise generator to use.
+##
+## This is useful if some project-specific buildsystem has been wrapped in a cmake script that won't perform an actual build. If used for this purpose, it should be set to "NMake Makefiles".
+##
+## ### OPTIONS
+## Additional options passed to CMake during the configuration.
+##
+## ### OPTIONS_RELEASE
+## Additional options passed to CMake during the Release configuration. These are in addition to `OPTIONS`.
+##
+## ### OPTIONS_DEBUG
+## Additional options passed to CMake during the Debug configuration. These are in addition to `OPTIONS`.
+##
+## ## Notes
+## This command supplies many common arguments to CMake. To see the full list, examine the source.
+##
+## ## Examples
+##
+## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 function(vcpkg_configure_cmake)
     cmake_parse_arguments(_csc "PREFER_NINJA" "SOURCE_PATH;GENERATOR" "OPTIONS;OPTIONS_DEBUG;OPTIONS_RELEASE" ${ARGN})
 
diff --git a/scripts/cmake/vcpkg_copy_pdbs.cmake b/scripts/cmake/vcpkg_copy_pdbs.cmake
index 61ad97728..ca55eb015 100644
--- a/scripts/cmake/vcpkg_copy_pdbs.cmake
+++ b/scripts/cmake/vcpkg_copy_pdbs.cmake
@@ -1,3 +1,19 @@
+## # vcpkg_copy_pdbs
+##
+## Automatically locate pdbs in the build tree and copy them adjacent to all DLLs.
+##
+## ## Usage
+## ```cmake
+## vcpkg_copy_pdbs()
+## ```
+##
+## ## Notes
+## This command should always be called by portfiles after they have finished rearranging the binary output.
+##
+## ## Examples
+##
+## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
 function(vcpkg_copy_pdbs)
 
     function(merge_filelist OUTVAR INVAR)
diff --git a/scripts/cmake/vcpkg_copy_tool_dependencies.cmake b/scripts/cmake/vcpkg_copy_tool_dependencies.cmake
index f8af19230..165f19ed1 100644
--- a/scripts/cmake/vcpkg_copy_tool_dependencies.cmake
+++ b/scripts/cmake/vcpkg_copy_tool_dependencies.cmake
@@ -1,5 +1,21 @@
-# Copy dlls for all tools in TOOL_DIR
-
+## # vcpkg_copy_tool_dependencies
+##
+## Copy all DLL dependencies of built tools into the tool folder.
+##
+## ## Usage
+## ```cmake
+## vcpkg_copy_tool_dependencies(<${CURRENT_PACKAGES_DIR}/tools/${PORT}>)
+## ```
+## ## Parameters
+## The path to the directory containing the tools.
+##
+## ## Notes
+## This command should always be called by portfiles after they have finished rearranging the binary output, if they have any tools.
+##
+## ## Examples
+##
+## * [glib](https://github.com/Microsoft/vcpkg/blob/master/ports/glib/portfile.cmake)
+## * [fltk](https://github.com/Microsoft/vcpkg/blob/master/ports/fltk/portfile.cmake)
 function(vcpkg_copy_tool_dependencies TOOL_DIR)
     macro(search_for_dependencies PATH_TO_SEARCH)
         file(GLOB TOOLS ${TOOL_DIR}/*.exe ${TOOL_DIR}/*.dll)
diff --git a/scripts/cmake/vcpkg_download_distfile.cmake b/scripts/cmake/vcpkg_download_distfile.cmake
index d086f9d23..006570195 100644
--- a/scripts/cmake/vcpkg_download_distfile.cmake
+++ b/scripts/cmake/vcpkg_download_distfile.cmake
@@ -1,4 +1,39 @@
-# Usage: vcpkg_download_distfile(<VAR> URLS <http://mainUrl> <http://mirror1> <http://mirror2> FILENAME <output.zip> SHA512 <5981de...>)
+## # vcpkg_download_distfile
+##
+## Download and cache a file needed for this port.
+##
+## ## Usage
+## ```cmake
+## vcpkg_download_distfile(
+##     <OUT_VARIABLE>
+##     URLS <http://mainUrl> <http://mirror1>...
+##     FILENAME <output.zip>
+##     SHA512 <5981de...>
+## )
+## ```
+## ## Parameters
+## ### OUT_VARIABLE
+## This variable will be set to the full path to the downloaded file. This can then immediately be passed in to [`vcpkg_extract_source_archive`](vcpkg_extract_source_archive.md) for sources.
+##
+## ### URLS
+## A list of URLs to be consulted. They will be tried in order until one of the downloaded files successfully matches the SHA512 given.
+##
+## ### FILENAME
+## The local name for the file. Files are shared between ports, so the file may need to be renamed to make it clearly attributed to this port and avoid conflicts.
+##
+## ### SHA512
+## The expected hash for the file.
+##
+## If this doesn't match the downloaded version, the build will be terminated with a message describing the mismatch.
+##
+## ## Notes
+## The command [`vcpkg_from_github`](vcpkg_from_github.md) should be used instead of this for downloading the main archive for GitHub projects.
+##
+## ## Examples
+##
+## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+## * [fontconfig](https://github.com/Microsoft/vcpkg/blob/master/ports/fontconfig/portfile.cmake)
+## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
 function(vcpkg_download_distfile VAR)
     set(oneValueArgs FILENAME SHA512)
     set(multipleValuesArgs URLS)
diff --git a/scripts/cmake/vcpkg_execute_required_process.cmake b/scripts/cmake/vcpkg_execute_required_process.cmake
index 7feff08b2..173bca6e9 100644
--- a/scripts/cmake/vcpkg_execute_required_process.cmake
+++ b/scripts/cmake/vcpkg_execute_required_process.cmake
@@ -1,4 +1,33 @@
-# Usage: vcpkg_execute_required_process(COMMAND <cmd> [<args>...] WORKING_DIRECTORY </path/to/dir> LOGNAME <my_log_name>)
+## # vcpkg_execute_required_process
+##
+## Execute a process with logging and fail the build if the command fails.
+##
+## ## Usage
+## ```cmake
+## vcpkg_execute_required_process(
+##     COMMAND <${PERL}> [<arguments>...]
+##     WORKING_DIRECTORY <${CURRENT_BUILDTREES_DIR}/${TARGET_TRIPLET}-dbg>
+##     LOGNAME <build-${TARGET_TRIPLET}-dbg>
+## )
+## ```
+## ## Parameters
+## ### COMMAND
+## The command to be executed, along with its arguments.
+##
+## ### WORKING_DIRECTORY
+## The directory to execute the command in.
+##
+## ### LOGNAME
+## The prefix to use for the log files.
+##
+## This should be a unique name for different triplets so that the logs don't conflict when building multiple at once.
+##
+## ## Examples
+##
+## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+## * [boost](https://github.com/Microsoft/vcpkg/blob/master/ports/boost/portfile.cmake)
+## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 function(vcpkg_execute_required_process)
     cmake_parse_arguments(vcpkg_execute_required_process "" "WORKING_DIRECTORY;LOGNAME" "COMMAND" ${ARGN})
     #debug_message("vcpkg_execute_required_process(${vcpkg_execute_required_process_COMMAND})")
diff --git a/scripts/cmake/vcpkg_extract_source_archive.cmake b/scripts/cmake/vcpkg_extract_source_archive.cmake
index 71654b452..5c16616c6 100644
--- a/scripts/cmake/vcpkg_extract_source_archive.cmake
+++ b/scripts/cmake/vcpkg_extract_source_archive.cmake
@@ -1,3 +1,32 @@
+## # vcpkg_extract_source_archive
+##
+## Extract an archive into the source directory.
+##
+## ## Usage
+## ```cmake
+## vcpkg_extract_source_archive(
+##     <${ARCHIVE}> [<${TARGET_DIRECTORY}>]
+## )
+## ```
+## ## Parameters
+## ### ARCHIVE
+## 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\`.
+##
+## This can be used to mimic git submodules, by extracting into a subdirectory of another archive.
+##
+## ## Notes
+## This command will also create a tracking file named <FILENAME>.extracted in the TARGET_DIRECTORY. This file, when present, will suppress the extraction of the archive.
+##
+## ## Examples
+##
+## * [libraw](https://github.com/Microsoft/vcpkg/blob/master/ports/libraw/portfile.cmake)
+## * [protobuf](https://github.com/Microsoft/vcpkg/blob/master/ports/protobuf/portfile.cmake)
+## * [msgpack](https://github.com/Microsoft/vcpkg/blob/master/ports/msgpack/portfile.cmake)
 include(vcpkg_execute_required_process)
 
 function(vcpkg_extract_source_archive_ex)
diff --git a/scripts/cmake/vcpkg_find_acquire_program.cmake b/scripts/cmake/vcpkg_find_acquire_program.cmake
index 127982842..e7e33c692 100644
--- a/scripts/cmake/vcpkg_find_acquire_program.cmake
+++ b/scripts/cmake/vcpkg_find_acquire_program.cmake
@@ -1,3 +1,37 @@
+## # vcpkg_find_acquire_program
+##
+## Download or find a well-known tool.
+##
+## ## Usage
+## ```cmake
+## vcpkg_find_acquire_program(<VAR>)
+## ```
+## ## Parameters
+## ### VAR
+## This variable specifies both the program to be acquired as well as the out parameter that will be set to the path of the program executable.
+##
+## ## Notes
+## The current list of programs includes:
+##
+## - 7Z
+## - BISON
+## - FLEX
+## - PERL
+## - PYTHON2
+## - PYTHON3
+## - JOM
+## - MESON
+## - NASM
+## - NINJA
+## - YASM
+##
+## Note that msys2 has a dedicated helper function: [`vcpkg_acquire_msys`](vcpkg_acquire_msys.md).
+##
+## ## Examples
+##
+## * [ffmpeg](https://github.com/Microsoft/vcpkg/blob/master/ports/ffmpeg/portfile.cmake)
+## * [openssl](https://github.com/Microsoft/vcpkg/blob/master/ports/openssl/portfile.cmake)
+## * [qt5](https://github.com/Microsoft/vcpkg/blob/master/ports/qt5/portfile.cmake)
 function(vcpkg_find_acquire_program VAR)
   if(${VAR} AND NOT ${VAR} MATCHES "-NOTFOUND")
     return()
diff --git a/scripts/cmake/vcpkg_from_github.cmake b/scripts/cmake/vcpkg_from_github.cmake
index f0f8dba8b..0ce485954 100644
--- a/scripts/cmake/vcpkg_from_github.cmake
+++ b/scripts/cmake/vcpkg_from_github.cmake
@@ -1,14 +1,52 @@
-# Usage:
-#   vcpkg_from_github(
-#     OUT_SOURCE_PATH <OutVar for SOURCE_PATH (SOURCE_PATH)>
-#     REPO <Repository (Microsoft/cpprestsdk)>
-#     REF <stable ref (v2.0.0)>
-#     SHA512 <SHA for REF (45d0d7f8cc350...)>
-#     HEAD_REF <unstable branch (master)>
-#   )
-#
-# Notes:
-#   This will export VCPKG_HEAD_VERSION variable during head builds.
+## # vcpkg_from_github
+##
+## Download and extract a project from GitHub. Enables support for `install --head`.
+##
+## ## Usage:
+## ```cmake
+## vcpkg_from_github(
+##     OUT_SOURCE_PATH <SOURCE_PATH>
+##     REPO <Microsoft/cpprestsdk>
+##     [REF <v2.0.0>]
+##     [SHA512 <45d0d7f8cc350...>]
+##     [HEAD_REF <master>]
+## )
+## ```
+##
+## ## Parameters:
+## ### OUT_SOURCE_PATH
+## Specifies the out-variable that will contain the extracted location.
+##
+## This should be set to `SOURCE_PATH` by convention.
+##
+## ### REPO
+## The organization or user and repository on GitHub.
+##
+## ### REF
+## A stable git commit-ish (ideally a tag) that will not change contents.
+##
+## If `REF` is specified, `SHA512` must also be specified.
+##
+## ### SHA512
+## The SHA512 hash that should match the archive (https://github.com/${REPO}/archive/${REF}.tar.gz).
+##
+## This is most easily determined by first setting it to `1`, then trying to build the port. The error message will contain the full hash, which can be copied back into the portfile.
+##
+## ### HEAD_REF
+## The unstable git commit-ish (ideally a branch) to pull for `--head` builds.
+##
+## For most projects, this should be `master`. The chosen branch should be one that is expected to be always buildable on all supported platforms.
+##
+## ## Notes:
+## At least one of `REF` and `HEAD_REF` must be specified.
+##
+## This exports the `VCPKG_HEAD_VERSION` variable during head builds.
+##
+## ## Examples:
+##
+## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+## * [ms-gsl](https://github.com/Microsoft/vcpkg/blob/master/ports/ms-gsl/portfile.cmake)
+## * [beast](https://github.com/Microsoft/vcpkg/blob/master/ports/beast/portfile.cmake)
 function(vcpkg_from_github)
     set(oneValueArgs OUT_SOURCE_PATH REPO REF SHA512 HEAD_REF)
     set(multipleValuesArgs)
diff --git a/scripts/cmake/vcpkg_install_cmake.cmake b/scripts/cmake/vcpkg_install_cmake.cmake
index 0ebff6961..f778007ef 100644
--- a/scripts/cmake/vcpkg_install_cmake.cmake
+++ b/scripts/cmake/vcpkg_install_cmake.cmake
@@ -1,3 +1,25 @@
+## # vcpkg_install_cmake
+##
+## Build and install a cmake project.
+##
+## ## Usage:
+## ```cmake
+## vcpkg_install_cmake([MSVC_64_TOOLSET])
+## ```
+##
+## ## Parameters:
+## ### MSVC_64_TOOLSET
+## This adds the `/p:PreferredToolArchitecture=x64` switch if the underlying buildsystem is MSBuild. Some large projects can run out of memory when linking if they use the 32-bit hosted tools.
+##
+## ## Notes:
+## This command should be preceeded by a call to [`vcpkg_configure_cmake()`](vcpkg_configure_cmake.md).
+##
+## ## Examples:
+##
+## * [zlib](https://github.com/Microsoft/vcpkg/blob/master/ports/zlib/portfile.cmake)
+## * [cpprestsdk](https://github.com/Microsoft/vcpkg/blob/master/ports/cpprestsdk/portfile.cmake)
+## * [poco](https://github.com/Microsoft/vcpkg/blob/master/ports/poco/portfile.cmake)
+## * [opencv](https://github.com/Microsoft/vcpkg/blob/master/ports/opencv/portfile.cmake)
 function(vcpkg_install_cmake)
     cmake_parse_arguments(_bc "MSVC_64_TOOLSET;DISABLE_PARALLEL" "" "" ${ARGN})