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,43 @@
+---
+title: documentationfile
+---
+
+Enable C# xmlDocumentationFile
+
+# Usage (2) #
+the DocumentationFile is used for adding the [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) added to functions/ variables, to a dll that has been packed inside a framework or other C# related.
+this can then be referenced inside another project by placing it next to the corresponding dll.
+
+this feature sets the [DocumentationFile](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) option inside csproj for each corresponding [configuration](https://premake.github.io/docs/configurations/)
+
+## 1) Default ##
+
+when you put documentationfile inside the project, the following filename/path will be generated:
+```%{targetdir}/%{prj.name}.xml```
+```lua
+documentationfile ""
+```
+
+## 2) Custom Directory ##
+
+when you put the following inside the project the following filename/path will be generated:
+```bin\test\%{prj.name}.xml```
+
+```lua
+documentationfile "bin/test"
+```
+<b>the path is relative to the project [location](https://premake.github.io/docs/location/)
+
+### Applies To ###
+
+The `project` scope.
+
+### Availability ###
+
+Visual Studio 2005
+
+## <b>NOTE !</b> ##
+it is recommended to use the default option because Visual Studio can only apply the DocumentationFile when it is placed directly next to the corresponding dll.
+
+## See Also ##
+more [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output)