add C# documentationFile feature

modules/vstudio/tests/_tests.lua

@@ -13,6 +13,7 @@ return {
 	"cs2005/test_no_warn.lua",
 	"cs2005/test_debug_props.lua",
 	"cs2005/test_debug_props_2019.lua",
+	"cs2005/test_documentation_file.lua",
 	"cs2005/test_files.lua",
 	"cs2005/test_icon.lua",
 	"cs2005/test_netcore.lua",

modules/vstudio/tests/cs2005/test_documentation_file.lua

@@ -0,0 +1,72 @@
+--
+-- tests/actions/vstudio/cs2005/test_documentation_file.lua
+-- Test DocumentationFile feature Visual Studio 2005+ C# project.
+-- Copyright (c) 2012-2023 Jason Perkins and the Premake project
+--
+	local p = premake
+	local suite = test.declare("vstudio_cs2005_documentation_file")
+	local dn2005 = p.vstudio.dotnetbase
+--
+-- Setup
+--
+
+	local wks, prj
+
+--
+-- Setup and teardown
+--
+	function suite.setup()
+		p.action.set("vs2010")
+		wks = test.createWorkspace()
+	 	configurations { "Debug", "Release" }
+		language "C#"
+		targetdir("test\\targetDir")
+	end
+
+	local function setConfig()
+		local cfg = test.getconfig(prj, "Debug")
+		dn2005.documentationfile(cfg);
+	end
+
+
+
+	local function prepare()
+		prj = test.getproject(wks, 1)
+	end
+
+	local function prepareEmpty()
+		prepare()
+		documentationfile ""
+		setConfig()
+	end
+
+	local function prepareDir()
+		prepare()
+		documentationfile "test"
+		setConfig()
+	end
+
+	local function prepareNull()
+		p.action.set("vs2010")
+		wks = test.createWorkspace()
+		setConfig()
+	end
+
+function suite.documentationFilePath()
+	prepareDir()
+	test.capture [[
+		<DocumentationFile>test\MyProject.xml</DocumentationFile>
+		]]
+end
+
+function suite.documentationEmpty()
+	prepareEmpty()
+	test.capture [[
+		<DocumentationFile>test\targetDir\MyProject.xml</DocumentationFile>
+		]]
+end
+
+function suite.documentationNull()
+	prepareNull()
+	test.isemptycapture()
+end

modules/vstudio/vs2005_csproj.lua

@@ -81,7 +81,8 @@
 			dotnetbase.debugProps,
 			dotnetbase.outputProps,
 			dotnetbase.compilerProps,
-			dotnetbase.NoWarn
+			dotnetbase.NoWarn,
+			dotnetbase.documentationFile,
 		}
 	end
 

modules/vstudio/vs2005_dotnetbase.lua

@@ -58,7 +58,7 @@
 		if dotnetbase.isNewFormatProject(prj) then
 			if prj.flags.WPF then
 				_p('<Project Sdk="Microsoft.NET.Sdk.WindowsDesktop">')
-			else				
+			else
 				_p('<Project Sdk="Microsoft.NET.Sdk">')
 			end
 		else
@@ -754,6 +754,13 @@
 		end
 	end
 
+	function dotnetbase.documentationfile(cfg)
+		if cfg.documentationFile then
+			local documentationFile = iif(cfg.documentationFile ~= "", cfg.documentationFile, cfg.targetdir)
+        	_p(2, string.format('<DocumentationFile>%s\\%s.xml</DocumentationFile>', vstudio.path(cfg, documentationFile),cfg.project.name))
+		end
+	end
+
 	function dotnetbase.isNewFormatProject(cfg)
 		local framework = cfg.dotnetframework
 		if not framework then
@@ -789,4 +796,4 @@
 		if cfg.clr == "Unsafe" then
 			_p(2,'<AllowUnsafeBlocks>true</AllowUnsafeBlocks>')
 		end
-	end
+	end

src/_premake_init.lua

@@ -765,6 +765,12 @@
 		}
 	}
 
+	api.register {
+		name = "documentationfile",
+		scope = "project",
+		kind = "string",
+	}
+
 	api.register {
 		name = "cdialect",
 		scope = "config",

website/docs/documentationFile.md

@@ -0,0 +1,46 @@
+Enables C# xmlDocumentationFile
+
+The `xmlDocumentationFile` option is used to include [XML comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) in a DLL that has been included in a .NET framework or another C# project. These XML comments can then be referenced by other projects when placed alongside the corresponding DLL.
+
+This feature sets the [documentationfile](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) option in a C# project's .csproj file for each respective [configuration](https://premake.github.io/docs/configurations/)
+
+## Usage ##
+To use xmlDocumentationFile, add the following line to your project configuration in your premake script:
+
+```lua
+documentationfile "targetdir"
+```
+### Parameters ###
+`targetdir` is the directory where the documentation file should be placed after building the project using visual studio.
+
+### Examples ###
+
+When you specify an empty string for `documentationfile`, the following filepath will be generated:
+```%{targetdir}/%{prj.name}.xml```
+```lua
+documentationfile ""
+```
+If you specify a custom target directory like this:
+```lua
+documentationfile "%{prj.location}/bin/test"
+```
+ the following filepath will be generated:
+```bin\test\%{prj.name}.xml```
+### Applies To ###
+
+Project configurations.
+
+### Availability ###
+
+Premake 5.0 or later.
+
+Visual studio 2005 C# is the only toolset currently supported.
+
+### Warning ###
+It's recommended to use the default option because Visual Studio may not detect the XML file if its name is not the same as the DLL.
+
+### See Also ###
+For more information on XML documentation in C#, refer to:
+1) [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/)
+2) [documentation file](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile)
+3) [configuration](https://premake.github.io/docs/configurations/)