From 34a8b7b83b4fac9f034ab5d863cb1a8516dde6cb Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 29 Jun 2023 17:49:05 +0200 Subject: [PATCH 01/20] added C# documentationFile feature --- modules/vstudio/vs2005_csproj.lua | 3 ++- modules/vstudio/vs2005_dotnetbase.lua | 12 ++++++++++-- src/_premake_init.lua | 6 ++++++ 3 files changed, 18 insertions(+), 3 deletions(-) diff --git a/modules/vstudio/vs2005_csproj.lua b/modules/vstudio/vs2005_csproj.lua index 83a6816319..43efdc3021 100644 --- a/modules/vstudio/vs2005_csproj.lua +++ b/modules/vstudio/vs2005_csproj.lua @@ -81,7 +81,8 @@ dotnetbase.debugProps, dotnetbase.outputProps, dotnetbase.compilerProps, - dotnetbase.NoWarn + dotnetbase.NoWarn, + dotnetbase.documentationFile, } end diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index e6371c8fca..cc46024b1b 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -58,7 +58,7 @@ if dotnetbase.isNewFormatProject(prj) then if prj.flags.WPF then _p('') - else + else _p('') end else @@ -754,6 +754,14 @@ end end + function dotnetbase.documentationFile(cfg) + if cfg.documentationFile and cfg.documentationFile ~= "" then + _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, cfg.documentationFile),cfg.project.name)) + else + _p(2, string.format('%s\\%s.xml',vstudio.path(cfg, cfg.targetdir),cfg.project.name)) + end + end + function dotnetbase.isNewFormatProject(cfg) local framework = cfg.dotnetframework if not framework then @@ -789,4 +797,4 @@ if cfg.clr == "Unsafe" then _p(2,'true') end - end \ No newline at end of file + end diff --git a/src/_premake_init.lua b/src/_premake_init.lua index 963fdaa9c5..2a24d94e6d 100644 --- a/src/_premake_init.lua +++ b/src/_premake_init.lua @@ -765,6 +765,12 @@ } } + api.register { + name = "documentationFile", + scope = "project", + kind = "string", + } + api.register { name = "cdialect", scope = "config", From 42128d0f730d427e78903d1557a8e9777e024dfb Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 29 Jun 2023 21:03:21 +0200 Subject: [PATCH 02/20] wrote unit tests for C# documentationFile --- modules/vstudio/tests/_tests.lua | 1 + .../tests/cs2005/test_documentation_file.lua | 82 +++++++++++++++++++ 2 files changed, 83 insertions(+) create mode 100644 modules/vstudio/tests/cs2005/test_documentation_file.lua diff --git a/modules/vstudio/tests/_tests.lua b/modules/vstudio/tests/_tests.lua index 07cd658a26..2e6e60c28d 100644 --- a/modules/vstudio/tests/_tests.lua +++ b/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", diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua new file mode 100644 index 0000000000..29de3a2032 --- /dev/null +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -0,0 +1,82 @@ +-- +-- tests/actions/vstudio/cs2005/test_debug_props.lua +-- Test debugging and optimization flags block of a Visual Studio 2005+ C# project. +-- Copyright (c) 2012-2013 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" } + -- project "documentationFile" + 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 prepareNil() + prepare() + setConfig() + end + + local function prepareEmpty() + prepare() + documentationFile "" + setConfig() + end + + local function prepareDir() + prepare() + documentationFile "test" + setConfig() + end + +-- +-- Test Eempty and Nil +-- + +function suite.documentationFileNil() + prepareNil() + test.capture([[ + test\targetDir\MyProject.xml + ]]) +end + +function suite.documentationFileEmpty() + prepareEmpty() + test.capture [[ + test\targetDir\MyProject.xml + ]] +end + +function suite.documentationFilePath() + prepareDir() + test.capture [[ + test\MyProject.xml + ]] + +end + From 753b78e39b22b0ccf65e51b6ececeac77b1530a6 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 29 Jun 2023 22:10:45 +0200 Subject: [PATCH 03/20] removed null opt to not enable documentationFile --- .../tests/cs2005/test_documentation_file.lua | 14 -------------- modules/vstudio/vs2005_dotnetbase.lua | 2 +- 2 files changed, 1 insertion(+), 15 deletions(-) diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua index 29de3a2032..fbf7b829e0 100644 --- a/modules/vstudio/tests/cs2005/test_documentation_file.lua +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -35,13 +35,6 @@ prj = test.getproject(wks, 1) end - - - local function prepareNil() - prepare() - setConfig() - end - local function prepareEmpty() prepare() documentationFile "" @@ -58,13 +51,6 @@ -- Test Eempty and Nil -- -function suite.documentationFileNil() - prepareNil() - test.capture([[ - test\targetDir\MyProject.xml - ]]) -end - function suite.documentationFileEmpty() prepareEmpty() test.capture [[ diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index cc46024b1b..fb783e8836 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -757,7 +757,7 @@ function dotnetbase.documentationFile(cfg) if cfg.documentationFile and cfg.documentationFile ~= "" then _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, cfg.documentationFile),cfg.project.name)) - else + elseif cfg.documentationFile then _p(2, string.format('%s\\%s.xml',vstudio.path(cfg, cfg.targetdir),cfg.project.name)) end end From c74f42f8b2305bd528134326548f1d028508ef79 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 29 Jun 2023 22:27:51 +0200 Subject: [PATCH 04/20] add documentationFile documentation --- website/docs/documentationFile.md | 41 +++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 website/docs/documentationFile.md diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md new file mode 100644 index 0000000000..c6c294f346 --- /dev/null +++ b/website/docs/documentationFile.md @@ -0,0 +1,41 @@ +--- +title: documentationFile +--- + +Enable C# xmlDocumentationFile + +# Usage (2) # +the xmlDocumentationFile is used for adding the [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) added to functions to a dll that has been packed inside a framework or other C# related dll that is refernced inside another project. + +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" +``` + +### Applies To ### + +The `project` scope. + +### Availability ### + +Visual Studio 2005 + +## NOTE ! ## +it is recommended to use the default option because visualStudio can only apply the xmlDocumentationFile when it is placed dirrectly next to the corresponding dll. + +## See Also ## +more [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) From 3c168d940c1419aab4cfbaf02356e47dbf502e49 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 29 Jun 2023 22:27:51 +0200 Subject: [PATCH 05/20] add documentationFile documentation --- website/docs/documentationFile.md | 41 +++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 website/docs/documentationFile.md diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md new file mode 100644 index 0000000000..da61fd4d76 --- /dev/null +++ b/website/docs/documentationFile.md @@ -0,0 +1,41 @@ +--- +title: documentationFile +--- + +Enable C# xmlDocumentationFile + +# Usage (2) # +the xmlDocumentationFile is used for adding the [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) added to functions to a dll that has been packed inside a framework or other C# related dll that is refernced inside another project. + +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" +``` + +### Applies To ### + +The `project` scope. + +### Availability ### + +Visual Studio 2005 + +## NOTE ! ## +it is recommended to use the default option because visualStudio can only apply the xmlDocumentationFile when it is placed dirrectly next to the corresponding dll. + +## See Also ## +more [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) From 3c60b2c32788c33088fd439671db51a55fd547f2 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Sat, 1 Jul 2023 10:31:58 +0200 Subject: [PATCH 06/20] added some extra info for custom dir --- website/docs/documentationFile.md | 1 + 1 file changed, 1 insertion(+) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index e8e3cbe430..fa586ff9bd 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -25,6 +25,7 @@ when you put the following inside the project the following filename/path will b ```lua documentationFile "bin/test" ``` +the path is rellative to the projects [location](https://premake.github.io/docs/location/) ### Applies To ### From aa6bac070916444b1c8ee26c24c8dcb28d9dacbd Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Tue, 4 Jul 2023 21:20:05 +0200 Subject: [PATCH 07/20] implemented comments --- .../tests/cs2005/test_documentation_file.lua | 33 +++++++++---------- modules/vstudio/vs2005_dotnetbase.lua | 2 +- src/_premake_init.lua | 2 +- website/docs/documentationFile.md | 13 ++++---- 4 files changed, 24 insertions(+), 26 deletions(-) diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua index fbf7b829e0..c6cecfd78b 100644 --- a/modules/vstudio/tests/cs2005/test_documentation_file.lua +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -1,7 +1,7 @@ -- -- tests/actions/vstudio/cs2005/test_debug_props.lua --- Test debugging and optimization flags block of a Visual Studio 2005+ C# project. --- Copyright (c) 2012-2013 Jason Perkins and the Premake project +-- 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") @@ -18,15 +18,14 @@ function suite.setup() p.action.set("vs2010") wks = test.createWorkspace() - configurations { "Debug", "Release" } - -- project "documentationFile" + configurations { "Debug", "Release" } language "C#" targetdir("test\\targetDir") end local function setConfig() local cfg = test.getconfig(prj, "Debug") - dn2005.documentationFile(cfg); + dn2005.documentationfile(cfg); end @@ -37,32 +36,30 @@ local function prepareEmpty() prepare() - documentationFile "" + documentationfile "" setConfig() end local function prepareDir() prepare() - documentationFile "test" + documentationfile "test" setConfig() end --- --- Test Eempty and Nil --- - -function suite.documentationFileEmpty() - prepareEmpty() - test.capture [[ - test\targetDir\MyProject.xml - ]] -end + local function prepareNull() + p.action.set("vs2010") + wks = test.createWorkspace() + setConfig() + end function suite.documentationFilePath() prepareDir() test.capture [[ test\MyProject.xml ]] - end +function suite.documentationNull() + prepareNull() + test.isemptycapture() +end diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index fb783e8836..d89d3f8f4f 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -754,7 +754,7 @@ end end - function dotnetbase.documentationFile(cfg) + function dotnetbase.documentationfile(cfg) if cfg.documentationFile and cfg.documentationFile ~= "" then _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, cfg.documentationFile),cfg.project.name)) elseif cfg.documentationFile then diff --git a/src/_premake_init.lua b/src/_premake_init.lua index 2a24d94e6d..00d9d42240 100644 --- a/src/_premake_init.lua +++ b/src/_premake_init.lua @@ -766,7 +766,7 @@ } api.register { - name = "documentationFile", + name = "documentationfile", scope = "project", kind = "string", } diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index fa586ff9bd..ebac962e6d 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -5,16 +5,17 @@ title: documentationFile Enable C# xmlDocumentationFile # Usage (2) # -the xmlDocumentationFile is used for adding the [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) added to functions to a dll that has been packed inside a framework or other C# related dll that is refernced inside another project. +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/) +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: +when you put documentationfile inside the project, the following filename/path will be generated: ```%{targetdir}/%{prj.name}.xml``` ```lua -documentationFile "" +documentationfile "" ``` ## 2) Custom Directory ## @@ -23,7 +24,7 @@ when you put the following inside the project the following filename/path will b ```bin\test\%{prj.name}.xml``` ```lua -documentationFile "bin/test" +documentationfile "bin/test" ``` the path is rellative to the projects [location](https://premake.github.io/docs/location/) @@ -36,7 +37,7 @@ The `project` scope. Visual Studio 2005 ## NOTE ! ## -it is recommended to use the default option because visualStudio can only apply the xmlDocumentationFile when it is placed dirrectly next to the corresponding dll. +it is recommended to use the default option because Visual Studio can only apply the DocumentationFile when it is placed dirrectly next to the corresponding dll. ## See Also ## more [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) From faae641a7cbf578d1404b036e7ba261873171f43 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Tue, 4 Jul 2023 21:21:55 +0200 Subject: [PATCH 08/20] fixed title --- website/docs/documentationFile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index ebac962e6d..40540ec7df 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -1,5 +1,5 @@ --- -title: documentationFile +title: documentationfile --- Enable C# xmlDocumentationFile From 17a9b04cf421779c08fb58f9688ba3b6666f07c2 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 6 Jul 2023 15:43:10 +0200 Subject: [PATCH 09/20] fixed spelling + addd test --- modules/vstudio/tests/cs2005/test_documentation_file.lua | 7 +++++++ modules/vstudio/vs2005_dotnetbase.lua | 7 +++---- website/docs/documentationFile.md | 4 ++-- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua index c6cecfd78b..da6cf88fbc 100644 --- a/modules/vstudio/tests/cs2005/test_documentation_file.lua +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -59,6 +59,13 @@ function suite.documentationFilePath() ]] end +function suite.documentationEmpty() + prepareEmpty() + test.capture [[ + test\targetDir\MyProject.xml + ]] +end + function suite.documentationNull() prepareNull() test.isemptycapture() diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index d89d3f8f4f..f418dd0293 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -755,10 +755,9 @@ end function dotnetbase.documentationfile(cfg) - if cfg.documentationFile and cfg.documentationFile ~= "" then - _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, cfg.documentationFile),cfg.project.name)) - elseif cfg.documentationFile then - _p(2, string.format('%s\\%s.xml',vstudio.path(cfg, cfg.targetdir),cfg.project.name)) + if cfg.documentationFile then + local documentationFile = iif(cfg.documentationFile ~= "", cfg.documentationFile, cfg.targetdir) + _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, documentationFile),cfg.project.name)) end end diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 40540ec7df..5e930029a5 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -26,7 +26,7 @@ when you put the following inside the project the following filename/path will b ```lua documentationfile "bin/test" ``` -the path is rellative to the projects [location](https://premake.github.io/docs/location/) +the path is relative to the project [location](https://premake.github.io/docs/location/) ### Applies To ### @@ -37,7 +37,7 @@ The `project` scope. Visual Studio 2005 ## NOTE ! ## -it is recommended to use the default option because Visual Studio can only apply the DocumentationFile when it is placed dirrectly next to the corresponding dll. +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) From ac1b8cb7f15884467549facf5675d5dfd7bbe506 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 6 Jul 2023 15:43:10 +0200 Subject: [PATCH 10/20] fixed spelling + addd test --- modules/vstudio/tests/cs2005/test_documentation_file.lua | 9 ++++++++- modules/vstudio/vs2005_dotnetbase.lua | 7 +++---- website/docs/documentationFile.md | 4 ++-- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua index c6cecfd78b..a811afc3f1 100644 --- a/modules/vstudio/tests/cs2005/test_documentation_file.lua +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -1,5 +1,5 @@ -- --- tests/actions/vstudio/cs2005/test_debug_props.lua +-- 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 -- @@ -59,6 +59,13 @@ function suite.documentationFilePath() ]] end +function suite.documentationEmpty() + prepareEmpty() + test.capture [[ + test\targetDir\MyProject.xml + ]] +end + function suite.documentationNull() prepareNull() test.isemptycapture() diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index d89d3f8f4f..f418dd0293 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -755,10 +755,9 @@ end function dotnetbase.documentationfile(cfg) - if cfg.documentationFile and cfg.documentationFile ~= "" then - _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, cfg.documentationFile),cfg.project.name)) - elseif cfg.documentationFile then - _p(2, string.format('%s\\%s.xml',vstudio.path(cfg, cfg.targetdir),cfg.project.name)) + if cfg.documentationFile then + local documentationFile = iif(cfg.documentationFile ~= "", cfg.documentationFile, cfg.targetdir) + _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, documentationFile),cfg.project.name)) end end diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 40540ec7df..5e930029a5 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -26,7 +26,7 @@ when you put the following inside the project the following filename/path will b ```lua documentationfile "bin/test" ``` -the path is rellative to the projects [location](https://premake.github.io/docs/location/) +the path is relative to the project [location](https://premake.github.io/docs/location/) ### Applies To ### @@ -37,7 +37,7 @@ The `project` scope. Visual Studio 2005 ## NOTE ! ## -it is recommended to use the default option because Visual Studio can only apply the DocumentationFile when it is placed dirrectly next to the corresponding dll. +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) From a228108e2003d5d5988bbba073184d41a101c854 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Wed, 30 Aug 2023 20:28:39 +0200 Subject: [PATCH 11/20] improved grammar / capitalization --- website/docs/documentationFile.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 5e930029a5..27dfbb97d3 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -1,18 +1,18 @@ --- -title: documentationfile +title: documentation file --- -Enable C# xmlDocumentationFile +Enables 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. +The Documentation File 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 project. +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/) +This feature sets the [Documentation File](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: +When you put **documentationfile** inside the project configuration, the following filename/path will be generated: ```%{targetdir}/%{prj.name}.xml``` ```lua documentationfile "" @@ -20,13 +20,13 @@ documentationfile "" ## 2) Custom Directory ## -when you put the following inside the project the following filename/path will be generated: +When you put the following inside the project configuration the following filename/path will be generated: ```bin\test\%{prj.name}.xml``` ```lua documentationfile "bin/test" ``` -the path is relative to the project [location](https://premake.github.io/docs/location/) +The path is relative to the project [location](https://premake.github.io/docs/location/) ### Applies To ### @@ -37,7 +37,7 @@ The `project` scope. Visual Studio 2005 ## NOTE ! ## -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. +It is recommended to use the default option because Visual Studio can only apply the Documentation File 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) +More [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) From fe84d57101716034c077f7ec35ff4693590aef39 Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Thu, 31 Aug 2023 14:48:00 +0200 Subject: [PATCH 12/20] changed styling of the documentation --- website/docs/documentationFile.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 27dfbb97d3..f93fa52c31 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -1,16 +1,17 @@ ---- -title: documentation file ---- - Enables C# xmlDocumentationFile -# Usage (2) # The Documentation File 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 project. This can then be referenced inside another project by placing it next to the corresponding dll. This feature sets the [Documentation File](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 ## +```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 put **documentationfile** inside the project configuration, the following filename/path will be generated: ```%{targetdir}/%{prj.name}.xml``` @@ -18,26 +19,24 @@ When you put **documentationfile** inside the project configuration, the followi documentationfile "" ``` -## 2) Custom Directory ## - When you put the following inside the project configuration the following filename/path will be generated: ```bin\test\%{prj.name}.xml``` ```lua documentationfile "bin/test" ``` -The path is relative to the project [location](https://premake.github.io/docs/location/) - ### Applies To ### -The `project` scope. +Project configurations. ### Availability ### -Visual Studio 2005 +Premake 5.0 or later. + +Visual Studio 2005 C# is the only toolset currently supported. -## NOTE ! ## +### Warning ### It is recommended to use the default option because Visual Studio can only apply the Documentation File when it is placed directly next to the corresponding DLL. -## See Also ## +### See Also ### More [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) From e831595328280640326c12a5f0cd9881e8bacc7c Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Sat, 2 Sep 2023 21:09:58 +0200 Subject: [PATCH 13/20] changed docs to fit api --- website/docs/documentationFile.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index f93fa52c31..52fbf25dc5 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -23,7 +23,7 @@ When you put the following inside the project configuration the following filena ```bin\test\%{prj.name}.xml``` ```lua -documentationfile "bin/test" +documentationfile "%{prj.location}/bin/test" ``` ### Applies To ### From dbd70b51b9fb252a56335f8e69486315b8fdb8fc Mon Sep 17 00:00:00 2001 From: robbe beernaert Date: Sat, 2 Sep 2023 21:42:01 +0200 Subject: [PATCH 14/20] added MSFT links to See Also --- website/docs/documentationFile.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 52fbf25dc5..3537a2a16f 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -40,3 +40,6 @@ It is recommended to use the default option because Visual Studio can only apply ### See Also ### More [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) +[xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) +[Documentation File](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) +[configuration](https://premake.github.io/docs/configurations/) From 19715ddcda23edf81a92f6d02e10f3d58831483d Mon Sep 17 00:00:00 2001 From: Beernaert Robbe Date: Sun, 1 Oct 2023 18:36:18 +0200 Subject: [PATCH 15/20] fixed capitalization --- website/docs/documentationFile.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 3537a2a16f..2deb939732 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -1,15 +1,15 @@ Enables C# xmlDocumentationFile -The Documentation File 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 project. -This can then be referenced inside another project by placing it next to the corresponding dll. +The documentation file is used for adding [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) to a dll that has been packed inside a framework or other C# related project. +This can then be referenced inside other projects by placing it next to the corresponding dll. -This feature sets the [Documentation File](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/) +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/) ```lua documentationfile "targetdir" ``` ### Parameters ### -`targetdir` is the directory where the Documentation File should be placed after building the project using Visual Studio. +`targetdir` is the directory where the documentation file should be placed after building the project using visual studio. ### Examples ### @@ -19,7 +19,7 @@ When you put **documentationfile** inside the project configuration, the followi documentationfile "" ``` -When you put the following inside the project configuration the following filename/path will be generated: +When you put the following inside the project configuration, the following filename/path will be generated: ```bin\test\%{prj.name}.xml``` ```lua @@ -33,13 +33,12 @@ Project configurations. Premake 5.0 or later. -Visual Studio 2005 C# is the only toolset currently supported. +Visual studio 2005 C# is the only toolset currently supported. ### Warning ### -It is recommended to use the default option because Visual Studio can only apply the Documentation File when it is placed directly next to the corresponding DLL. - +default option is recommendes because visual studio cannot detect the xml file if the name is the same as the dll. ### See Also ### More [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) -[Documentation File](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) +[documentation file](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) [configuration](https://premake.github.io/docs/configurations/) From ce31e60d7654ff5aa149b6e1bfe803cadafe416f Mon Sep 17 00:00:00 2001 From: Beernaert Robbe Date: Sun, 1 Oct 2023 18:52:48 +0200 Subject: [PATCH 16/20] changed wording/ capitalization of documentation --- website/docs/documentationFile.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 2deb939732..71eaa698c9 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -1,9 +1,11 @@ Enables C# xmlDocumentationFile -The documentation file is used for adding [xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) to a dll that has been packed inside a framework or other C# related project. -This can then be referenced inside other projects by placing it next to the corresponding dll. +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 inside csproj for each corresponding [configuration](https://premake.github.io/docs/configurations/) +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" @@ -13,18 +15,17 @@ documentationfile "targetdir" ### Examples ### -When you put **documentationfile** inside the project configuration, the following filename/path will be generated: +When you specify an empty string for `documentationfile`, the following filename/path will be generated: ```%{targetdir}/%{prj.name}.xml``` ```lua documentationfile "" ``` - -When you put the following inside the project configuration, the following filename/path will be generated: -```bin\test\%{prj.name}.xml``` - +If you specify a custom target directory like this: ```lua documentationfile "%{prj.location}/bin/test" ``` + the following filename/path will be generated: +```bin\test\%{prj.name}.xml``` ### Applies To ### Project configurations. @@ -36,9 +37,10 @@ Premake 5.0 or later. Visual studio 2005 C# is the only toolset currently supported. ### Warning ### -default option is recommendes because visual studio cannot detect the xml file if the name is the same as the dll. +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 ### -More [info](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/#create-xml-documentation-output) -[xml comments](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/) -[documentation file](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/compiler-options/output#documentationfile) -[configuration](https://premake.github.io/docs/configurations/) +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/) From 40167feef191a194d7586b53ed775ad5ec0f4292 Mon Sep 17 00:00:00 2001 From: Beernaert Robbe Date: Mon, 2 Oct 2023 13:47:51 +0200 Subject: [PATCH 17/20] removed the slashes! --- website/docs/documentationFile.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/documentationFile.md b/website/docs/documentationFile.md index 71eaa698c9..2fdf143263 100644 --- a/website/docs/documentationFile.md +++ b/website/docs/documentationFile.md @@ -5,7 +5,7 @@ The `xmlDocumentationFile` option is used to include [XML comments](https://lear 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: +To use xmlDocumentationFile, add the following line to your project configuration in your premake script: ```lua documentationfile "targetdir" @@ -15,7 +15,7 @@ documentationfile "targetdir" ### Examples ### -When you specify an empty string for `documentationfile`, the following filename/path will be generated: +When you specify an empty string for `documentationfile`, the following filepath will be generated: ```%{targetdir}/%{prj.name}.xml``` ```lua documentationfile "" @@ -24,7 +24,7 @@ If you specify a custom target directory like this: ```lua documentationfile "%{prj.location}/bin/test" ``` - the following filename/path will be generated: + the following filepath will be generated: ```bin\test\%{prj.name}.xml``` ### Applies To ### From 9707d8f52334123f3f6014f6a312e5a43bd69471 Mon Sep 17 00:00:00 2001 From: Beernaert Robbe Date: Thu, 5 Oct 2023 19:45:42 +0200 Subject: [PATCH 18/20] added documenationfile to the sidebar --- website/sidebars.js | 1 + 1 file changed, 1 insertion(+) diff --git a/website/sidebars.js b/website/sidebars.js index ecf0edba68..8cdfed655f 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -131,6 +131,7 @@ module.exports = { 'display', 'docdir', 'docname', + 'documentationfile', 'dofileopt', 'dotnetframework', 'dpiawareness', From 3533b2aaeb5e8b0ec93e45dad11e09aa7eafa440 Mon Sep 17 00:00:00 2001 From: lolrobbe2 <90089980+lolrobbe2@users.noreply.github.com> Date: Tue, 31 Oct 2023 21:13:06 +0100 Subject: [PATCH 19/20] Rename documentationFile.md to documentationfile.md --- website/docs/{documentationFile.md => documentationfile.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename website/docs/{documentationFile.md => documentationfile.md} (100%) diff --git a/website/docs/documentationFile.md b/website/docs/documentationfile.md similarity index 100% rename from website/docs/documentationFile.md rename to website/docs/documentationfile.md From f50609c99154dbd7af0c4d1688dbbfbcbc2134c0 Mon Sep 17 00:00:00 2001 From: Beernaert Robbe Date: Sun, 9 Jun 2024 21:27:18 +0200 Subject: [PATCH 20/20] added support for newer tag (functional result stays the same) --- .../tests/cs2005/test_documentation_file.lua | 16 ++++++++++++++++ modules/vstudio/vs2005_csproj.lua | 2 +- modules/vstudio/vs2005_dotnetbase.lua | 8 ++++++-- 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/modules/vstudio/tests/cs2005/test_documentation_file.lua b/modules/vstudio/tests/cs2005/test_documentation_file.lua index a811afc3f1..aa214c0750 100644 --- a/modules/vstudio/tests/cs2005/test_documentation_file.lua +++ b/modules/vstudio/tests/cs2005/test_documentation_file.lua @@ -59,6 +59,14 @@ function suite.documentationFilePath() ]] end +function suite.documentationFilePath_vs2017up() + p.action.set("vs2017") + prepareDir() + test.capture [[ + test\MyProject.xml + ]] +end + function suite.documentationEmpty() prepareEmpty() test.capture [[ @@ -66,7 +74,15 @@ function suite.documentationEmpty() ]] end +function suite.documentationEmpty_vs2017up() + p.action.set("vs2017") + prepareEmpty() + test.capture [[true]] +end + function suite.documentationNull() prepareNull() test.isemptycapture() end + + diff --git a/modules/vstudio/vs2005_csproj.lua b/modules/vstudio/vs2005_csproj.lua index fe8873ecf1..4c0c1fd833 100644 --- a/modules/vstudio/vs2005_csproj.lua +++ b/modules/vstudio/vs2005_csproj.lua @@ -82,7 +82,7 @@ dotnetbase.outputProps, dotnetbase.compilerProps, dotnetbase.additionalProps, - dotnetbase.NoWarn,, + dotnetbase.NoWarn, dotnetbase.documentationFile, } end diff --git a/modules/vstudio/vs2005_dotnetbase.lua b/modules/vstudio/vs2005_dotnetbase.lua index 460d921709..dcc16260be 100644 --- a/modules/vstudio/vs2005_dotnetbase.lua +++ b/modules/vstudio/vs2005_dotnetbase.lua @@ -769,8 +769,12 @@ function dotnetbase.documentationfile(cfg) if cfg.documentationFile then - local documentationFile = iif(cfg.documentationFile ~= "", cfg.documentationFile, cfg.targetdir) - _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, documentationFile),cfg.project.name)) + if _ACTION > "vs2015" and cfg.documentationFile == "" then + _p(2,'true') + else + local documentationFile = iif(cfg.documentationFile ~= "", cfg.documentationFile, cfg.targetdir) + _p(2, string.format('%s\\%s.xml', vstudio.path(cfg, documentationFile),cfg.project.name)) + end end end