diff --git a/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md b/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md index f473832a3e455..4166a1fa597dc 100644 --- a/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md +++ b/docs/framework/reflection-and-codedom/how-to-create-an-xml-documentation-file-using-codedom.md @@ -10,10 +10,11 @@ helpviewer_keywords: - "Code Document Object Model, generating XML documentation" ms.assetid: e3b80484-36b9-41dd-9d21-a2f9a36381dc --- -# How to: Create an XML Documentation File Using CodeDOM +# How to: Create an XML documentation file using CodeDOM + CodeDOM can be used to create code that generates XML documentation. The process involves creating the CodeDOM graph that contains the XML documentation comments, generating the code, and compiling the generated code with the compiler option that creates the XML documentation output. -### To create a CodeDOM graph that contains XML documentation comments +## Create a CodeDOM graph 1. Create a containing the CodeDOM graph for the sample application. @@ -22,27 +23,28 @@ CodeDOM can be used to create code that generates XML documentation. The process [!code-csharp[CodeDomHelloWorldSample#4](../../../samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs#4)] [!code-vb[CodeDomHelloWorldSample#4](../../../samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb#4)] -### To generate the code from the CodeCompileUnit +### Generate the code from the CodeCompileUnit 1. Use the method to generate the code and create a source file to be compiled. [!code-csharp[CodeDomHelloWorldSample#5](../../../samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs#5)] [!code-vb[CodeDomHelloWorldSample#5](../../../samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb#5)] -### To compile the code and generate the documentation file +### Compile the code and generate the documentation file 1. Add the **/doc** compiler option to the property of a object and pass the object to the method to create the XML documentation file when the code is compiled. [!code-csharp[CodeDomHelloWorldSample#6](../../../samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs#6)] [!code-vb[CodeDomHelloWorldSample#6](../../../samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb#6)] -## Example - The following code example creates a CodeDOM graph with documentation comments, generates a code file from the graph, and compiles the file and creates an associated XML documentation file. +## Example + +The following code example creates a CodeDOM graph with documentation comments, generates a code file from the graph, and compiles the file and creates an associated XML documentation file. [!code-csharp[CodeDomHelloWorldSample#1](../../../samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs#1)] [!code-vb[CodeDomHelloWorldSample#1](../../../samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb#1)] - The code example creates the following XML documentation in the HelloWorldDoc.xml file. + The code example creates the following XML documentation in the *HelloWorldDoc.xml* file. ```xml @@ -54,8 +56,8 @@ CodeDOM can be used to create code that generates XML documentation. The process Create a Hello World application. - - + + @@ -67,12 +69,12 @@ CodeDOM can be used to create code that generates XML documentation. The process ``` -## Compiling the Code +## Compile permissions -- This code example requires the `FullTrust` permission set to execute successfully. +This code example requires the `FullTrust` permission set to execute successfully. ## See also -- [Documenting Your Code with XML](../../visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md) -- [XML Documentation Comments](../../csharp/programming-guide/xmldoc/index.md) -- [XML Documentation](/cpp/ide/xml-documentation-visual-cpp) +- [Document your code with XML (Visual Basic)](../../visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md) +- [XML documentation comments](../../csharp/programming-guide/xmldoc/index.md) +- [XML documentation (C++)](/cpp/ide/xml-documentation-visual-cpp) 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 d5ed90175db9d..091e2afb7de09 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 @@ -7,13 +7,13 @@ helpviewer_keywords: - "Visual Basic code, documenting with XML" ms.assetid: a0d35dc7-c5f9-4d74-92ff-a1c6f28d5235 --- -# Documenting Your Code with XML (Visual Basic) +# Document your code with XML (Visual Basic) -In Visual Basic, you can document your code using XML +In Visual Basic, you can document your code using XML. -## XML Documentation Comments +## 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 name as your project and the .xml extension. 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 more information, see [-doc](../../reference/command-line-compiler/doc.md). 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. @@ -21,7 +21,7 @@ XML documentation starts with `'''`. The processing of these comments has some r - The documentation must be well-formed XML. If the XML is not well formed, a warning is generated and the documentation file contains a comment saying that an error was encountered. -- Developers are free to create their own set of tags. There is a recommended set of tags (see "Related Sections" in this topic). Some of the recommended tags have special meanings: +- Developers are free to create their own set of tags. There is a recommended set of tags (see [XML Comment Tags](../../language-reference/xmldoc/index.md)). Some of the recommended tags have special meanings: - The \ tag is used to describe parameters. If used, the compiler will verify that the parameter exists and that all parameters are described in the documentation. If the verification fails, the compiler issues a warning. @@ -29,7 +29,7 @@ XML documentation starts with `'''`. The processing of these comments has some r - The \ tag is used by IntelliSense in Visual Studio to display additional information about a type or member. -## Related Sections +## Related sections For details on creating an XML file with documentation comments, see the following topics: diff --git a/samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs b/samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs index a8a371bef5113..6e413dc877bf2 100644 --- a/samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs +++ b/samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs @@ -22,11 +22,11 @@ static void Main(string[] args) cu = BuildHelloWorldGraph(); - // + // StreamWriter sourceFile = new StreamWriter(sourceFileName); provider.GenerateCodeFromCompileUnit(cu, sourceFile, null); sourceFile.Close(); - // + // // CompilerParameters opt = new CompilerParameters(new string[]{ @@ -82,9 +82,9 @@ public static CodeCompileUnit BuildHelloWorldGraph() class1.Comments.Add(new CodeCommentStatement("", true)); class1.Comments.Add(new CodeCommentStatement( "Create a Hello World application.", true)); + class1.Comments.Add(new CodeCommentStatement("", true)); class1.Comments.Add(new CodeCommentStatement( @"", true)); - class1.Comments.Add(new CodeCommentStatement("", true)); // Add the new type to the namespace type collection. samples.Types.Add(class1); diff --git a/samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb b/samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb index 10ac8cca66b61..2d6d59f312f2e 100644 --- a/samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb +++ b/samples/snippets/visualbasic/VS_Snippets_CLR/CodeDomHelloWorldSample/vb/program.vb @@ -4,8 +4,6 @@ Imports System.CodeDom.Compiler Imports System.IO Imports System.Text.RegularExpressions - - Class Program Private Shared providerName As String = "vb" Private Shared sourceFileName As String = "test.vb" @@ -21,7 +19,6 @@ Class Program cu = BuildHelloWorldGraph() ' - Dim sourceFile As New StreamWriter(sourceFileName) LogMessage("Generating code...") @@ -56,10 +53,8 @@ Class Program End Sub - ' - ' Build a Hello World program graph using - ' System.CodeDom types. + ' Build a Hello World program graph using System.CodeDom types. Public Shared Function BuildHelloWorldGraph() As CodeCompileUnit ' Create a new CodeCompileUnit to contain ' the program graph. @@ -80,10 +75,10 @@ Class Program class1.Comments.Add(New CodeCommentStatement("", True)) class1.Comments.Add(New CodeCommentStatement( _ "Create a Hello World application.", True)) + class1.Comments.Add(New CodeCommentStatement("", True)) class1.Comments.Add(New CodeCommentStatement( _ "", True)) - class1.Comments.Add(New CodeCommentStatement("", True)) ' Add the new type to the namespace type collection. samples.Types.Add(class1) @@ -139,7 +134,6 @@ Class Program End Sub - Shared Sub OutputResults(ByVal results As CompilerResults) LogMessage(("NativeCompilerReturnValue=" & _ results.NativeCompilerReturnValue.ToString())) @@ -150,4 +144,4 @@ Class Program End Sub End Class -' \ No newline at end of file +'