VS: Add VS_DOTNET_DOCUMENTATION_FILE property

Add a `VS_DOTNET_DOCUMENTATION_FILE` target property to tell VS
generators to add a `DocumentationFile` setting in `.csproj` files.

Fixes: #19784

Help/manual/cmake-properties.7.rst

@@ -342,6 +342,7 @@ Properties on Targets
    /prop_tgt/VS_DOTNET_REFERENCES
    /prop_tgt/VS_DOTNET_REFERENCES_COPY_LOCAL
    /prop_tgt/VS_DOTNET_TARGET_FRAMEWORK_VERSION
+   /prop_tgt/VS_DOTNET_DOCUMENTATION_FILE
    /prop_tgt/VS_DPI_AWARE
    /prop_tgt/VS_GLOBAL_KEYWORD
    /prop_tgt/VS_GLOBAL_PROJECT_TYPES

Help/prop_tgt/VS_DOTNET_DOCUMENTATION_FILE.rst

@@ -0,0 +1,6 @@
+VS_DOTNET_DOCUMENTATION_FILE
+----------------------------
+
+Visual Studio managed project .NET documentation output
+
+Sets the target XML documentation file output.

Help/release/dev/vs_dotnet_documentation_file.rst

@@ -0,0 +1,6 @@
+vs_dotnet_documentation_file
+----------------------------
+
+* The :prop_tgt:`VS_DOTNET_DOCUMENTATION_FILE` target property was added
+  to tell :ref:`Visual Studio Generators` to generate a ``DocumentationFile``
+  reference in ``.csproj`` files.

Source/cmVisualStudio10TargetGenerator.cxx

@@ -676,6 +676,8 @@ void cmVisualStudio10TargetGenerator::Generate()
 
       this->WritePlatformExtensions(e1);
     }
+
+    this->WriteDotNetDocumentationFile(e0);
     Elem(e0, "PropertyGroup").Attribute("Label", "UserMacros");
     this->WriteWinRTPackageCertificateKeyFile(e0);
     this->WritePathAndIncrementalLinkOptions(e0);
@@ -910,6 +912,18 @@ void cmVisualStudio10TargetGenerator::WriteDotNetReferenceCustomTags(
   }
 }
 
+void cmVisualStudio10TargetGenerator::WriteDotNetDocumentationFile(Elem& e0)
+{
+  std::string const documentationFile =
+    this->GeneratorTarget->GetSafeProperty("VS_DOTNET_DOCUMENTATION_FILE");
+
+  if (this->ProjectType == csproj && !documentationFile.empty()) {
+    Elem e1(e0, "PropertyGroup");
+    Elem e2(e1, "DocumentationFile");
+    e2.Content(documentationFile);
+  }
+}
+
 void cmVisualStudio10TargetGenerator::WriteEmbeddedResourceGroup(Elem& e0)
 {
   std::vector<cmSourceFile const*> resxObjs;

Source/cmVisualStudio10TargetGenerator.h

@@ -79,6 +79,7 @@ private:
   void WriteDotNetReference(Elem& e1, std::string const& ref,
                             std::string const& hint,
                             std::string const& config);
+  void WriteDotNetDocumentationFile(Elem& e0);
   void WriteImports(Elem& e0);
   void WriteDotNetReferenceCustomTags(Elem& e2, std::string const& ref);
   void WriteEmbeddedResourceGroup(Elem& e0);

Tests/RunCMake/VS10Project/RunCMakeTest.cmake

@@ -15,6 +15,7 @@ run_cmake(VsDebuggerCommand)
 run_cmake(VsDebuggerCommandArguments)
 run_cmake(VsDebuggerEnvironment)
 run_cmake(VsCSharpCustomTags)
+run_cmake(VsCSharpDocumentationFile)
 run_cmake(VsCSharpReferenceProps)
 run_cmake(VsCSharpWithoutSources)
 run_cmake(VsCSharpDeployFiles)

Tests/RunCMake/VS10Project/VsCSharpDocumentationFile-check.cmake

@@ -0,0 +1,26 @@
+#
+# Check C# VS project for required elements
+#
+set(csProjectFile "${RunCMake_TEST_BINARY_DIR}/foo.csproj")
+if(NOT EXISTS "${csProjectFile}")
+  set(RunCMake_TEST_FAILED "Project file ${csProjectFile} does not exist.")
+  return()
+endif()
+
+file(STRINGS "${csProjectFile}" lines)
+
+set(HAVE_DocumentationFile 0)
+foreach(line IN LISTS lines)
+  if(line MATCHES "^ *<DocumentationFile>([^<>]+)</DocumentationFile>")
+    if(HAVE_DocumentationFile)
+      set(RunCMake_TEST_FAILED "Documentation node has been generated more than once for\n  ${csProjectFile}")
+      return()
+    endif()
+    set(HAVE_DocumentationFile 1)
+  endif()
+endforeach()
+
+if(NOT HAVE_DocumentationFile)
+  set(RunCMake_TEST_FAILED "Documentation node has not been generated for\n  ${csProjectFile}")
+  return()
+endif()

Tests/RunCMake/VS10Project/VsCSharpDocumentationFile.cmake

@@ -0,0 +1,8 @@
+set(CMAKE_CONFIGURATION_TYPES Debug)
+enable_language(CSharp)
+
+add_library(foo SHARED
+  foo.cs)
+
+set_target_properties(foo PROPERTIES
+  VS_DOTNET_DOCUMENTATION_FILE foo.xml)