move seealso tag outside summary (dotnet#18822)

Author: gewarren

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 <xref:System.CodeDom.CodeCompileUnit> 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 <xref:System.CodeDom.Compiler.CodeDomProvider.GenerateCodeFromCompileUnit%2A> 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 <xref:System.CodeDom.Compiler.CompilerParameters.CompilerOptions%2A> property of a <xref:System.CodeDom.Compiler.CompilerParameters> object and pass the object to the <xref:System.CodeDom.Compiler.CodeDomProvider.CompileAssemblyFromFile%2A> 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  
 <?xml version="1.0" ?>
@@ -54,8 +56,8 @@ CodeDOM can be used to create code that generates XML documentation. The process
     <member name="T:Samples.Class1">  
       <summary>  
         Create a Hello World application.
-        <seealso cref="M:Samples.Class1.Main" />
-      </summary>  
+      </summary>
+      <seealso cref="M:Samples.Class1.Main" />
     </member>  
     <member name="M:Samples.Class1.Main">  
       <summary>  
@@ -67,12 +69,12 @@ CodeDOM can be used to create code that generates XML documentation. The process
 </doc>  
 ```  
 
-## 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)

docs/visual-basic/programming-guide/program-structure/documenting-your-code-with-xml.md

@@ -7,29 +7,29 @@ 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.
 
 XML documentation starts with `'''`. The processing of these comments has some restrictions:
 
 - 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 \<param> 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.
 
   - The `cref` attribute can be attached to any tag to provide a reference to a code element. The compiler verifies that this code element exists. If the verification fails, the compiler issues a warning. The compiler also respects any `Imports` statements when looking for a type described in the `cref` attribute.
 
   - The \<summary> 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:
 

samples/snippets/csharp/VS_Snippets_CLR/CodeDomHelloWorldSample/cs/program.cs

@@ -22,11 +22,11 @@ static void Main(string[] args)
 
             cu = BuildHelloWorldGraph();
 
-     	     //<Snippet5>
+            //<Snippet5>
             StreamWriter sourceFile = new StreamWriter(sourceFileName);
             provider.GenerateCodeFromCompileUnit(cu, sourceFile, null);
             sourceFile.Close();
-	     //</Snippet5>
+            //</Snippet5>
 
             //<Snippet6>
             CompilerParameters opt = new CompilerParameters(new string[]{
@@ -82,9 +82,9 @@ public static CodeCompileUnit BuildHelloWorldGraph()
             class1.Comments.Add(new CodeCommentStatement("<summary>", true));
             class1.Comments.Add(new CodeCommentStatement(
                 "Create a Hello World application.", true));
+            class1.Comments.Add(new CodeCommentStatement("</summary>", true));
             class1.Comments.Add(new CodeCommentStatement(
                 @"<seealso cref=" + '"' + "Class1.Main" + '"' + "/>", true));
-            class1.Comments.Add(new CodeCommentStatement("</summary>", true));
 
             // Add the new type to the namespace type collection.
             samples.Types.Add(class1);

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()
 
         '<Snippet5>
-
         Dim sourceFile As New StreamWriter(sourceFileName)
 
         LogMessage("Generating code...")
@@ -56,10 +53,8 @@ Class Program
 
     End Sub
 
-
     '<Snippet2>
-    ' 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("<summary>", True))
         class1.Comments.Add(New CodeCommentStatement( _
             "Create a Hello World application.", True))
+        class1.Comments.Add(New CodeCommentStatement("</summary>", True))
         class1.Comments.Add(New CodeCommentStatement( _
             "<seealso cref=" & ControlChars.Quote & "Class1.Main" & _
             ControlChars.Quote & "/>", True))
-        class1.Comments.Add(New CodeCommentStatement("</summary>", 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
-'</Snippet1>
+'</Snippet1>