[docs] link to new functions in deprecated warnings (#17179)

* [docs] link to new functions in deprecated warnings

* [docs] add deprecation messages to portfile-functions.md

* [docs] also update documentation in .cmake files

* [docs] introduce new directive DEPRECATED BY in the documentation generation script and use that directive

* Trigger Build

* Trigger Build

* Trigger Build

12 files changed, 56 insertions, 50 deletions

diff --git a/docs/maintainers/portfile-functions.md b/docs/maintainers/portfile-functions.md
index 842ef6137..ccc06db88 100644
--- a/docs/maintainers/portfile-functions.md
+++ b/docs/maintainers/portfile-functions.md
@@ -5,7 +5,7 @@
 - [vcpkg\_acquire\_msys](vcpkg_acquire_msys.md)
 - [vcpkg\_add\_to\_path](vcpkg_add_to_path.md)
 - [vcpkg\_apply\_patches](vcpkg_apply_patches.md) (deprecated)
-- [vcpkg\_build\_cmake](vcpkg_build_cmake.md)
+- [vcpkg\_build\_cmake](vcpkg_build_cmake.md) (deprecated, use [vcpkg\_cmake\_build](ports/vcpkg-cmake/vcpkg_cmake_build.md))
 - [vcpkg\_build\_gn](vcpkg_build_gn.md)
 - [vcpkg\_build\_make](vcpkg_build_make.md)
 - [vcpkg\_build\_msbuild](vcpkg_build_msbuild.md)
@@ -18,7 +18,7 @@
 - [vcpkg\_clean\_executables\_in\_bin](vcpkg_clean_executables_in_bin.md)
 - [vcpkg\_clean\_msbuild](vcpkg_clean_msbuild.md)
 - [vcpkg\_common\_definitions](vcpkg_common_definitions.md)
-- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md)
+- [vcpkg\_configure\_cmake](vcpkg_configure_cmake.md) (deprecated, use [vcpkg\_cmake\_configure](ports/vcpkg-cmake/vcpkg_cmake_configure.md))
 - [vcpkg\_configure\_gn](vcpkg_configure_gn.md)
 - [vcpkg\_configure\_make](vcpkg_configure_make.md)
 - [vcpkg\_configure\_meson](vcpkg_configure_meson.md)
@@ -36,7 +36,7 @@
 - [vcpkg\_fail\_port\_install](vcpkg_fail_port_install.md)
 - [vcpkg\_find\_acquire\_program](vcpkg_find_acquire_program.md)
 - [vcpkg\_find\_fortran](vcpkg_find_fortran.md)
-- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md)
+- [vcpkg\_fixup\_cmake\_targets](vcpkg_fixup_cmake_targets.md) (deprecated, use [vcpkg\_cmake\_config\_fixup](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md))
 - [vcpkg\_fixup\_pkgconfig](vcpkg_fixup_pkgconfig.md)
 - [vcpkg\_from\_bitbucket](vcpkg_from_bitbucket.md)
 - [vcpkg\_from\_git](vcpkg_from_git.md)
@@ -45,7 +45,7 @@
 - [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\_cmake](vcpkg_install_cmake.md) (deprecated, use [vcpkg\_cmake\_install](ports/vcpkg-cmake/vcpkg_cmake_install.md))
 - [vcpkg\_install\_gn](vcpkg_install_gn.md)
 - [vcpkg\_install\_make](vcpkg_install_make.md)
 - [vcpkg\_install\_meson](vcpkg_install_meson.md)
diff --git a/docs/maintainers/vcpkg_apply_patches.md b/docs/maintainers/vcpkg_apply_patches.md
index 76197ecca..a3aad0714 100644
--- a/docs/maintainers/vcpkg_apply_patches.md
+++ b/docs/maintainers/vcpkg_apply_patches.md
@@ -1,6 +1,6 @@
 # vcpkg_apply_patches
 
-**This function has been deprecated in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.**
+**This function has been deprecated in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.**
 
 The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_apply_patches.md).
 
diff --git a/docs/maintainers/vcpkg_build_cmake.md b/docs/maintainers/vcpkg_build_cmake.md
index eb7cb6e50..380136c8f 100644
--- a/docs/maintainers/vcpkg_build_cmake.md
+++ b/docs/maintainers/vcpkg_build_cmake.md
@@ -1,8 +1,8 @@
 # vcpkg_build_cmake
 
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
+**This function has been deprecated in favor of [`vcpkg_cmake_build`](ports/vcpkg-cmake/vcpkg_cmake_build.md) from the vcpkg-cmake port.**
 
-**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_build_cmake.md).
 
 Build a cmake project.
 
diff --git a/docs/maintainers/vcpkg_configure_cmake.md b/docs/maintainers/vcpkg_configure_cmake.md
index fd434cf22..195017b3c 100644
--- a/docs/maintainers/vcpkg_configure_cmake.md
+++ b/docs/maintainers/vcpkg_configure_cmake.md
@@ -1,8 +1,8 @@
 # vcpkg_configure_cmake
 
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
+**This function has been deprecated in favor of [`vcpkg_cmake_configure`](ports/vcpkg-cmake/vcpkg_cmake_configure.md) from the vcpkg-cmake port.**
 
-**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_configure_cmake.md).
 
 Configure CMake for Debug and Release builds of a project.
 
diff --git a/docs/maintainers/vcpkg_fixup_cmake_targets.md b/docs/maintainers/vcpkg_fixup_cmake_targets.md
index 704ac4ad1..b9ca9c4d7 100644
--- a/docs/maintainers/vcpkg_fixup_cmake_targets.md
+++ b/docs/maintainers/vcpkg_fixup_cmake_targets.md
@@ -1,8 +1,8 @@
 # vcpkg_fixup_cmake_targets
 
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
+**This function has been deprecated in favor of [`vcpkg_cmake_config_fixup`](ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup.md) from the vcpkg-cmake-config port.**
 
-**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_fixup_cmake_targets.md).
 
 Merge release and debug CMake targets and configs to support multiconfig generators.
 
diff --git a/docs/maintainers/vcpkg_install_cmake.md b/docs/maintainers/vcpkg_install_cmake.md
index 10c9d0b32..f8d3b6107 100644
--- a/docs/maintainers/vcpkg_install_cmake.md
+++ b/docs/maintainers/vcpkg_install_cmake.md
@@ -1,8 +1,8 @@
 # vcpkg_install_cmake
 
-The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
+**This function has been deprecated in favor of [`vcpkg_cmake_install`](ports/vcpkg-cmake/vcpkg_cmake_install.md) from the vcpkg-cmake port.**
 
-**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
+The latest version of this document lives in the [vcpkg repo](https://github.com/Microsoft/vcpkg/blob/master/docs/maintainers/vcpkg_install_cmake.md).
 
 Build and install a cmake project.
 
diff --git a/docs/regenerate.ps1 b/docs/regenerate.ps1
index 4c847f75a..df78e2fca 100755
--- a/docs/regenerate.ps1
+++ b/docs/regenerate.ps1
@@ -20,6 +20,8 @@ class CMakeDocumentation {
     [String[]]$ActualDocumentation
     [Bool]$IsDeprecated
     [String]$DeprecationMessage
+    [String]$DeprecatedByName
+    [String]$DeprecatedByPath
     [Bool]$HasError
 }
 
@@ -111,9 +113,19 @@ function FinalDocFile
     $documentation += $Docs.ActualDocumentation[0] # name line
     if ($Docs.IsDeprecated)
     {
-        if ($null -eq $Docs.DeprecationMessage)
+        if ($null -eq $Docs.DeprecationMessage -or $Docs.DeprecationMessage -match '^ *$')
         {
-            $documentation += @("", "**This function has been deprecated**")
+            if(![string]::IsNullOrEmpty($Docs.DeprecatedByName))
+            {
+                $message = " in favor of [``$($Docs.DeprecatedByName)``]($($Docs.DeprecatedByPath)$($Docs.DeprecatedByName).md)"
+                $Docs.DeprecatedByPath -match '^ports/([a-z\-]+)/$' | Out-Null
+                $port = $matches[1]
+                if(![string]::IsNullOrEmpty($port))
+                {
+                    $message += " from the $port port."
+                }
+            }
+            $documentation += @("", "**This function has been deprecated$message**")
         }
         else
         {
@@ -153,10 +165,12 @@ function ParseCmakeDocComment
     {
         $Docs.IsDeprecated = $True
     }
-    elseif($contents[0] -match '^# DEPRECATED: (.*)$')
+    elseif($contents[0] -match '^# DEPRECATED( BY (([^/]+/)+)(.+))?((: *)(.*))?$')
     {
         $Docs.IsDeprecated = $True
-        $Docs.DeprecationMessage = $matches[1]
+        $Docs.DeprecatedByPath = $matches[2]
+        $Docs.DeprecatedByName = $matches[4]
+        $Docs.DeprecationMessage = $matches[7]
     }
 
     [String]$startCommentRegex = '#\[(=*)\['
@@ -292,29 +306,32 @@ $portfileFunctionsContent = @(
     '',
     '# Portfile helper functions')
 
+function GetDeprecationMessage
+{
+    Param(
+        [CMakeDocumentation]$Doc
+    )
+    if ($Doc.IsDeprecated)
+    {
+        $message = " (deprecated"
+        if(![string]::IsNullOrEmpty($Doc.DeprecatedByName))
+        {
+            $message += ", use [$($($Doc.DeprecatedByName) -replace '_','\_')]($($Doc.DeprecatedByPath)$($Doc.DeprecatedByName).md)"
+        }
+        $message += ")"
+    }
+    $message
+}
+
 $DocsName = @{ expression = { Split-Path -LeafBase $_.Filename } }
 $tableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
     $name = Split-Path -LeafBase $_.Filename
-    if ($_.IsDeprecated)
-    {
-        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md) (deprecated)"
-    }
-    else
-    {
-        $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)"
-    }
+    $portfileFunctionsContent += "- [$($name -replace '_','\_')]($name.md)" + $(GetDeprecationMessage $_)
 }
 $portfileFunctionsContent += @("", "## Internal Functions", "")
 $internalTableOfContents | Sort-Object -Property $DocsName -Culture '' | ForEach-Object {
     $name = Split-Path -LeafBase $_.Filename
-    if ($_.IsDeprecated)
-    {
-        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md) (deprecated)"
-    }
-    else
-    {
-        $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)"
-    }
+    $portfileFunctionsContent += "- [$($name -replace '_','\_')](internal/$name.md)" + $(GetDeprecationMessage $_)
 }
 
 $portfileFunctionsContent += @("", "## Scripts from Ports")
@@ -324,14 +341,7 @@ $portTableOfContents.GetEnumerator() | ForEach-Object {
     $portfileFunctionsContent += @("", "### [$portName](ports/$portName.md)", "")
     $cmakeDocs | ForEach-Object {
         $name = Split-Path -LeafBase $_.Filename
-        if ($_.IsDeprecated)
-        {
-            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md) (deprecated)"
-        }
-        else
-        {
-            $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)"
-        }
+        $portfileFunctionsContent += "- [$($name -replace '_','\_')](ports/$portName/$name.md)" + $(GetDeprecationMessage $_)
     }
 }
 
diff --git a/scripts/cmake/vcpkg_apply_patches.cmake b/scripts/cmake/vcpkg_apply_patches.cmake
index bd4325af4..dae9e6018 100644
--- a/scripts/cmake/vcpkg_apply_patches.cmake
+++ b/scripts/cmake/vcpkg_apply_patches.cmake
@@ -1,4 +1,4 @@
-# DEPRECATED: in favor of the `PATCHES` argument to `vcpkg_from_github()` et al.
+# DEPRECATED: in favor of the `PATCHES` argument to [`vcpkg_from_github()`](vcpkg_from_github.md) et al.
 
 #[===[.md
 # vcpkg_apply_patches
diff --git a/scripts/cmake/vcpkg_build_cmake.cmake b/scripts/cmake/vcpkg_build_cmake.cmake
index 523999b4e..1bf89830e 100644
--- a/scripts/cmake/vcpkg_build_cmake.cmake
+++ b/scripts/cmake/vcpkg_build_cmake.cmake
@@ -1,8 +1,7 @@
+# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_build
 #[===[.md:
 # vcpkg_build_cmake
 
-**This function has been deprecated in favor of `vcpkg_cmake_build` from the vcpkg-cmake port.**
-
 Build a cmake project.
 
 ## Usage:
diff --git a/scripts/cmake/vcpkg_configure_cmake.cmake b/scripts/cmake/vcpkg_configure_cmake.cmake
index 1cac9f015..fdf054e43 100644
--- a/scripts/cmake/vcpkg_configure_cmake.cmake
+++ b/scripts/cmake/vcpkg_configure_cmake.cmake
@@ -1,8 +1,7 @@
+# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_configure
 #[===[.md:
 # vcpkg_configure_cmake
 
-**This function has been deprecated in favor of `vcpkg_cmake_configure` from the vcpkg-cmake port.**
-
 Configure CMake for Debug and Release builds of a project.
 
 ## Usage
diff --git a/scripts/cmake/vcpkg_fixup_cmake_targets.cmake b/scripts/cmake/vcpkg_fixup_cmake_targets.cmake
index f38270e8c..e6fbe785b 100644
--- a/scripts/cmake/vcpkg_fixup_cmake_targets.cmake
+++ b/scripts/cmake/vcpkg_fixup_cmake_targets.cmake
@@ -1,8 +1,7 @@
+# DEPRECATED BY ports/vcpkg-cmake-config/vcpkg_cmake_config_fixup
 #[===[.md:
 # vcpkg_fixup_cmake_targets
 
-**This function has been deprecated in favor of `vcpkg_cmake_config_fixup` from the vcpkg-cmake-config port.**
-
 Merge release and debug CMake targets and configs to support multiconfig generators.
 
 Additionally corrects common issues with targets, such as absolute paths and incorrectly placed binaries.
diff --git a/scripts/cmake/vcpkg_install_cmake.cmake b/scripts/cmake/vcpkg_install_cmake.cmake
index 82e6af05d..b94a3a484 100644
--- a/scripts/cmake/vcpkg_install_cmake.cmake
+++ b/scripts/cmake/vcpkg_install_cmake.cmake
@@ -1,8 +1,7 @@
+# DEPRECATED BY ports/vcpkg-cmake/vcpkg_cmake_install
 #[===[.md:
 # vcpkg_install_cmake
 
-**This function has been deprecated in favor of `vcpkg_cmake_install` from the vcpkg-cmake port.**
-
 Build and install a cmake project.
 
 ## Usage: