diff --git a/docs/core/project-sdk/msbuild-props.md b/docs/core/project-sdk/msbuild-props.md index e8f8ff15d5519..15deb5f7dd6fa 100644 --- a/docs/core/project-sdk/msbuild-props.md +++ b/docs/core/project-sdk/msbuild-props.md @@ -1,7 +1,7 @@ --- title: MSBuild properties for Microsoft.NET.Sdk description: Reference for the MSBuild properties and items that are understood by the .NET SDK. -ms.date: 09/02/2021 +ms.date: 11/22/2021 ms.topic: reference ms.custom: updateeachrelease --- @@ -317,7 +317,7 @@ The `RuntimeIdentifiers` property lets you specify a semicolon-delimited list of ``` -## SatelliteResourceLanguages +### SatelliteResourceLanguages The `SatelliteResourceLanguages` property lets you specify which languages you want to preserve satellite resource assemblies for during build and publish. Many NuGet packages include localized resource satellite assemblies in the main package. For projects that reference these NuGet packages that don't require localized resources, the localized assemblies can unnecessarily inflate the build and publish output size. By adding the `SatelliteResourceLanguages` property to your project file, only localized assemblies for the languages you specify will be included in the build and publish output. For example, in the following project file, only English (US) resource satellite assemblies will be retained. @@ -348,8 +348,10 @@ For more information about deployment, see [.NET application deployment](../depl The following MSBuild properties are documented in this section: +- [DocumentationFile](#documentationfile) - [EmbeddedResourceUseDependentUponConvention](#embeddedresourceusedependentuponconvention) - [EnablePreviewFeatures](#enablepreviewfeatures) +- [GenerateDocumentationFile](#generatedocumentationfile) - [GenerateRequiresPreviewFeaturesAttribute](#generaterequirespreviewfeaturesattribute) - [OptimizeImplicitlyTriggeredBuild](#optimizeimplicitlytriggeredbuild) @@ -390,6 +392,30 @@ An analyzer warns if this attribute is present on dependencies for projects wher Library authors who intend to ship preview assemblies should set this property to `True`. If an assembly needs to ship with a mixture of preview and non-preview APIs, see the [GenerateRequiresPreviewFeaturesAttribute](#generaterequirespreviewfeaturesattribute) section below. +### DocumentationFile + +The `DocumentationFile` property lets you specify a file name for the XML file that contains the documentation for your library. For IntelliSense to function correctly with your documentation, the file name must be the same as the assembly name and must be in the same directory as the assembly. If you don't specify this property but you do set [GenerateDocumentationFile](#generatedocumentationfile) to `true`, the name of the documentation file defaults to the name of your assembly but with an *.xml* file extension. For this reason, it's often easier to omit this property and use the [GenerateDocumentationFile property](#generatedocumentationfile) instead. + +If you specify this property but you set [GenerateDocumentationFile](#generatedocumentationfile) to `false`, the compiler *does not* generate a documentation file. If you specify this property and omit the [GenerateDocumentationFile property](#generatedocumentationfile), the compiler *does* generate a documentation file. + +```xml + + path/to/file.xml + +``` + +### GenerateDocumentationFile + +The `GenerateDocumentationFile` property controls whether the compiler generates an XML documentation file for your library. If you set this property to `true` and you don't specify a file name via the [DocumentationFile property](#documentationfile), the generated XML file is placed in the same output directory as your assembly and has the same file name (but with an *.xml* extension). + +```xml + + true + +``` + +For more information about generating documentation from code comments, see [XML documentation comments (C#)](../../csharp/language-reference/xmldoc/index.md), [Document your code with XML (Visual Basic)](../../visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md), or [Document your code with XML (F#)](../../fsharp/language-reference/xml-documentation.md). + ### GenerateRequiresPreviewFeaturesAttribute The `GenerateRequiresPreviewFeaturesAttribute` property is closely related to the [EnablePreviewFeatures](#enablepreviewfeatures) property. If your library uses preview features but you don't want the entire assembly to be marked with the attribute, which would require any consumers to [enable preview features](#enablepreviewfeatures), set this property to `False`. diff --git a/docs/csharp/language-reference/compiler-options/output.md b/docs/csharp/language-reference/compiler-options/output.md index 949f6a4a4d1de..c216d2572f4c1 100644 --- a/docs/csharp/language-reference/compiler-options/output.md +++ b/docs/csharp/language-reference/compiler-options/output.md @@ -36,6 +36,8 @@ The source code file that contains Main or top-level statements is output first > [!NOTE] > The **DocumentationFile** option applies to all files in the project. To disable warnings related to documentation comments for a specific file or section of code, use [#pragma warning](../preprocessor-directives.md#pragma-warning). +This option can be used in any .NET SDK-style project. For more information, see [DocumentationFile property](../../../core/project-sdk/msbuild-props.md#documentationfile). + ## OutputAssembly The **OutputAssembly** option specifies the name of the output file. The output path specifies the folder where compiler output is placed. diff --git a/docs/csharp/language-reference/xmldoc/index.md b/docs/csharp/language-reference/xmldoc/index.md index df0ad1e2a69c2..9cb372ff2cbc2 100644 --- a/docs/csharp/language-reference/xmldoc/index.md +++ b/docs/csharp/language-reference/xmldoc/index.md @@ -42,7 +42,7 @@ You create documentation for your code by writing special comment fields indicat public class MyClass {} ``` -You set the [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) option and the compiler will find all comment fields with XML tags in the source code and create an XML documentation file from those comments. When this option is enabled, the compiler generates the [CS1591](../compiler-messages/cs1591.md) warning for any publicly visible member declared in your project without XML documentation comments. +You set either the [**GenerateDocumentationFile**](../../../core/project-sdk/msbuild-props.md#generatedocumentationfile) or [**DocumentationFile**](../../language-reference/compiler-options/output.md#documentationfile) option, and the compiler will find all comment fields with XML tags in the source code and create an XML documentation file from those comments. When this option is enabled, the compiler generates the [CS1591](../compiler-messages/cs1591.md) warning for any publicly visible member declared in your project without XML documentation comments. ## XML comment formats diff --git a/docs/fsharp/language-reference/xml-documentation.md b/docs/fsharp/language-reference/xml-documentation.md index e00e7ad2161b1..b565377ec3728 100644 --- a/docs/fsharp/language-reference/xml-documentation.md +++ b/docs/fsharp/language-reference/xml-documentation.md @@ -26,6 +26,8 @@ You can generate the XML file at compile time by doing one of the following: true ``` + For more information, see [GenerateDocumentationFile property](../../core/project-sdk/msbuild-props.md#generatedocumentationfile). + - If you are developing an application using Visual Studio, right-click on the project and select **Properties**. In the properties dialog, select the **Build** tab, and check **XML documentation file**. You can also change the location to which the compiler writes the file. There are two ways to write XML documentation comments: with and without XML tags. Both use triple-slash comments. diff --git a/docs/visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md b/docs/visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md index 395ab58866312..734a2223bcdfa 100644 --- a/docs/visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md +++ b/docs/visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Document your code with XML (Visual Basic)" title: "Documenting Your Code with XML" -ms.date: 07/20/2015 +ms.date: 11/22/2021 helpviewer_keywords: - "XML [Visual Basic], documenting code" - "XML comments, Visual Basic" @@ -14,7 +14,7 @@ In Visual Basic, you can document your code using XML. ## XML documentation comments -Visual Basic provides an easy way to automatically create XML documentation for projects. You can automatically generate an XML skeleton for your types and members, and then provide summaries, descriptive documentation for each parameter, and other remarks. With the appropriate setup, the XML documentation is automatically emitted into an XML file with the same root file name as your project. For more information, see [-doc](../../reference/command-line-compiler/doc.md). +Visual Basic provides an easy way to automatically create XML documentation for projects. You can automatically generate an XML skeleton for your types and members, and then provide summaries, descriptive documentation for each parameter, and other remarks. With the appropriate setup, the XML documentation is automatically emitted into an XML file with the same root file name as your project. For information about configuring the generation of the XML documentation file, see [-doc compiler option](../../reference/command-line-compiler/doc.md) and [GenerateDocumentationFile MSBuild property](../../../core/project-sdk/msbuild-props.md#generatedocumentationfile). The XML file can be consumed or otherwise manipulated as XML. This file is located in the same directory as the output .exe or .dll file of your project.