diff --git a/docs/csharp/programming-guide/xmldoc/code-inline.md b/docs/csharp/programming-guide/xmldoc/code-inline.md index c1b2be6b258dc..8e0da49ab63b7 100644 --- a/docs/csharp/programming-guide/xmldoc/code-inline.md +++ b/docs/csharp/programming-guide/xmldoc/code-inline.md @@ -27,7 +27,7 @@ ms.assetid: aad5b16e-a29e-445e-bd0d-eea0b138d7b2 ## Remarks -The \ tag gives you a way to indicate that text within a description should be marked as code. Use [\](./code.md) to indicate multiple lines as code. +The `` tag gives you a way to indicate that text within a description should be marked as code. Use [\](./code.md) to indicate multiple lines as code. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/code.md b/docs/csharp/programming-guide/xmldoc/code.md index 7c904fe2c15c9..9e156b74959f2 100644 --- a/docs/csharp/programming-guide/xmldoc/code.md +++ b/docs/csharp/programming-guide/xmldoc/code.md @@ -25,13 +25,13 @@ ms.assetid: f235e3bc-a709-43cf-8a9f-bd57cabdf6da ## Remarks -The \ tag gives you a way to indicate multiple lines as code. Use [\](./code-inline.md) to indicate that text within a description should be marked as code. +The `` tag is used to indicate multiple lines of code. Use [\](./code-inline.md) to indicate that single-line text within a description should be marked as code. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. ## Example -See the [\](./example.md) topic for an example of how to use the \ tag. +See the [\](./example.md) article for an example of how to use the `` tag. ## See also diff --git a/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md b/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md index d8a0db5413dce..b05d87824d047 100644 --- a/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md +++ b/docs/csharp/programming-guide/xmldoc/delimiters-for-documentation-tags.md @@ -13,10 +13,10 @@ The use of XML doc comments requires delimiters, which indicate to the compiler - `///` - Single-line delimiter. This is the form that is shown in documentation examples and used by the Visual C# project templates. If there is a white space character following the delimiter, that character is not included in the XML output. + Single-line delimiter. This is the form that is shown in documentation examples and used by the C# project templates. If there is a white space character following the delimiter, that character is not included in the XML output. > [!NOTE] - > The Visual Studio IDE has a feature called Smart Comment Editing that automatically inserts the \ and \ tags and moves your cursor within these tags after you type the `///` delimiter in the Code Editor. You can turn this feature on or off in the [Options dialog box](/visualstudio/ide/reference/options-text-editor-csharp-advanced). + > The Visual Studio integrated development environment (IDE) automatically inserts the `` and `` tags and moves your cursor within these tags after you type the `///` delimiter in the code editor. You can turn this feature on or off in the [Options dialog box](/visualstudio/ide/reference/options-text-editor-csharp-advanced). - `/** */` @@ -26,13 +26,13 @@ The use of XML doc comments requires delimiters, which indicate to the compiler - On the line that contains the `/**` delimiter, if the remainder of the line is white space, the line is not processed for comments. If the first character after the `/**` delimiter is white space, that white space character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment. - - On the line that contains the `*/` delimiter, if there is only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment, subject to the pattern-matching rules described in the following bullet. + - On the line that contains the `*/` delimiter, if there is only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment. - For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line. The pattern can consist of optional white space and an asterisk (`*`), followed by more optional white space. If the compiler finds a common pattern at the beginning of each line that does not begin with the `/**` delimiter or the `*/` delimiter, it ignores that pattern for each line. The following examples illustrate these rules. - - The only part of the following comment that will be processed is the line that begins with ``. The three tag formats produce the same comments. + - The only part of the following comment that's processed is the line that begins with ``. The three tag formats produce the same comments. ```csharp /** text */ @@ -71,7 +71,7 @@ The use of XML doc comments requires delimiters, which indicate to the compiler * * text * text2 - * + * */ ``` diff --git a/docs/csharp/programming-guide/xmldoc/example.md b/docs/csharp/programming-guide/xmldoc/example.md index 37477aa71827d..24fa6a4f9a90b 100644 --- a/docs/csharp/programming-guide/xmldoc/example.md +++ b/docs/csharp/programming-guide/xmldoc/example.md @@ -25,7 +25,7 @@ ms.assetid: 32d6e73b-2554-4abb-83ee-a1e321334fd2 ## Remarks -The \ tag lets you specify an example of how to use a method or other library member. This commonly involves using the [\](./code.md) tag. +The `` tag lets you specify an example of how to use a method or other library member. This commonly involves using the [\](./code.md) tag. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/exception.md b/docs/csharp/programming-guide/xmldoc/exception.md index 8552ef4834861..b81e8ae450ca8 100644 --- a/docs/csharp/programming-guide/xmldoc/exception.md +++ b/docs/csharp/programming-guide/xmldoc/exception.md @@ -31,7 +31,7 @@ ms.assetid: dd73aac5-3c74-4fcf-9498-f11bff3a2f3c ## Remarks -The \ tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers. +The `` tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md b/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md index 0006816b1b5e5..23ca8999de891 100644 --- a/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md +++ b/docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md @@ -102,28 +102,28 @@ The example generates an *.xml* file with the following contents. ## Compiling the code -To compile the example, type the following command line: +To compile the example, enter the following command: `csc XMLsample.cs /doc:XMLsample.xml` -This command creates the XML file *XMLsample.xml*, which you can view in your browser or by using the TYPE command. +This command creates the XML file *XMLsample.xml*, which you can view in your browser or by using the `TYPE` command. ## Robust programming -XML documentation starts with ///. When you create a new project, the wizards put some starter /// lines in for you. The processing of these comments has some restrictions: +XML documentation starts with `///`. When you create a new project, the wizards put some starter `///` lines in for you. 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 will contain a comment that says that an error was encountered. - Developers are free to create their own set of tags. There is a [recommended set of tags](recommended-tags-for-documentation-comments.md). Some of the recommended tags have special meanings: - - The \ tag is used to describe parameters. If used, the compiler verifies that the parameter exists and that all parameters are described in the documentation. If the verification failed, the compiler issues a warning. + - The `` tag is used to describe parameters. If used, the compiler verifies 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 failed, the compiler issues a warning. The compiler respects any `using` statements when it looks for a type described in the `cref` attribute. + - The `cref` attribute can be attached to any tag to reference a code element. The compiler verifies that this code element exists. If the verification fails, the compiler issues a warning. The compiler respects any `using` statements when it looks for a type described in the `cref` attribute. - - The \ tag is used by IntelliSense inside Visual Studio to display additional information about a type or member. + - The `` tag is used by IntelliSense inside Visual Studio to display additional information about a type or member. > [!NOTE] - > The XML file does not provide full information about the type and members (for example, it does not contain any type information). To get full information about a type or member, the documentation file must be used together with reflection on the actual type or member. + > The XML file does not provide full information about the type and members (for example, it does not contain any type information). To get full information about a type or member, use the documentation file together with reflection on the actual type or member. ## See also diff --git a/docs/csharp/programming-guide/xmldoc/include.md b/docs/csharp/programming-guide/xmldoc/include.md index f19716fd54ba6..18c41f3a89581 100644 --- a/docs/csharp/programming-guide/xmldoc/include.md +++ b/docs/csharp/programming-guide/xmldoc/include.md @@ -37,13 +37,13 @@ The ID for the tag that precedes the comments. Enclose the ID in double quotatio ## Remarks -The \ tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. +The `` tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file. By putting the documentation in a separate file, you can apply source control to the documentation separately from the source code. One person can have the source code file checked out and someone else can have the documentation file checked out. -The \ tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your \ use. +The `` tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your `` use. ## Example -This is a multifile example. The following is the first file, which uses \. +This is a multifile example. The following is the first file, which uses ``. [!code-csharp[csProgGuideDocComments#5](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#5)] @@ -69,7 +69,7 @@ The summary for this other type. ## Program output -The following output is generated when you compile the Test and Test2 classes with the following command line: `-doc:DocFileName.xml.` In Visual Studio, you specify the XML doc comments option in the Build pane of the Project Designer. When the C# compiler sees the \ tag, it will search for documentation comments in xml_include_tag.doc instead of the current source file. The compiler then generates DocFileName.xml, and this is the file that is consumed by documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to produce the final documentation. +The following output is generated when you compile the Test and Test2 classes with the following command line: `-doc:DocFileName.xml.` In Visual Studio, you specify the XML doc comments option in the Build pane of the Project Designer. When the C# compiler sees the `` tag, it searches for documentation comments in *xml_include_tag.doc* instead of the current source file. The compiler then generates *DocFileName.xml*, and this is the file that is consumed by documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to produce the final documentation. ```xml diff --git a/docs/csharp/programming-guide/xmldoc/list.md b/docs/csharp/programming-guide/xmldoc/list.md index 1e5de96690bf0..53bca4e378b7b 100644 --- a/docs/csharp/programming-guide/xmldoc/list.md +++ b/docs/csharp/programming-guide/xmldoc/list.md @@ -42,11 +42,11 @@ ms.assetid: c9620b1b-c2e6-43f1-ab88-8ab47308ffec ## Remarks -The \ block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading. +The `` block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading. -Each item in the list is specified with an \ block. When creating a definition list, you will need to specify both `term` and `description`. However, for a table, bulleted list, or numbered list, you only need to supply an entry for `description`. +Each item in the list is specified with an `` block. When creating a definition list, you will need to specify both `term` and `description`. However, for a table, bulleted list, or numbered list, you only need to supply an entry for `description`. -A list or table can have as many \ blocks as needed. +A list or table can have as many `` blocks as needed. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/para.md b/docs/csharp/programming-guide/xmldoc/para.md index d8afb1d4b652d..84dfaadfb182b 100644 --- a/docs/csharp/programming-guide/xmldoc/para.md +++ b/docs/csharp/programming-guide/xmldoc/para.md @@ -25,13 +25,13 @@ ms.assetid: c74b8705-29df-40b1-bff5-237492b0e978 ## Remarks -The \ tag is for use inside a tag, such as [\](./summary.md), [\](./remarks.md), or [\](./returns.md), and lets you add structure to the text. +The `` tag is for use inside a tag, such as [\](./summary.md), [\](./remarks.md), or [\](./returns.md), and lets you add structure to the text. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. ## Example -See [\](./summary.md) for an example of using \. +See [\](./summary.md) for an example of using ``. ## See also diff --git a/docs/csharp/programming-guide/xmldoc/param.md b/docs/csharp/programming-guide/xmldoc/param.md index ba6645c56a5f5..09235a5a29919 100644 --- a/docs/csharp/programming-guide/xmldoc/param.md +++ b/docs/csharp/programming-guide/xmldoc/param.md @@ -29,9 +29,9 @@ ms.assetid: 46d329b1-5b84-4537-9e17-73ca97313e4e ## Remarks -The \ tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple \ tags. +The `` tag should be used in the comment for a method declaration to describe one of the parameters for the method. To document multiple parameters, use multiple `` tags. -The text for the \ tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report. +The text for the `` tag is displayed in IntelliSense, the Object Browser, and the Code Comment Web Report. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/paramref.md b/docs/csharp/programming-guide/xmldoc/paramref.md index 54ef7ac64b7a9..636fa5c4c6fd7 100644 --- a/docs/csharp/programming-guide/xmldoc/paramref.md +++ b/docs/csharp/programming-guide/xmldoc/paramref.md @@ -25,7 +25,7 @@ ms.assetid: 756c24c1-f591-40e8-a838-559761539b0b ## Remarks -The \ tag gives you a way to indicate that a word in the code comments, for example in a \ or \ block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font. +The `` tag gives you a way to indicate that a word in the code comments, for example in a `` or `` block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/permission.md b/docs/csharp/programming-guide/xmldoc/permission.md index c8e574659d0d7..ab3b67cb6b3dd 100644 --- a/docs/csharp/programming-guide/xmldoc/permission.md +++ b/docs/csharp/programming-guide/xmldoc/permission.md @@ -31,7 +31,7 @@ ms.assetid: 769e93fe-8404-443f-bf99-577aa42b6a49 ## Remarks -The \ tag lets you document the access of a member. The class lets you specify access to a member. +The `` tag lets you document the access of a member. The class lets you specify access to a member. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md b/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md index 59638c133dd04..be4488ff1899d 100644 --- a/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md +++ b/docs/csharp/programming-guide/xmldoc/processing-the-xml-file.md @@ -6,31 +6,33 @@ helpviewer_keywords: - "XML [C#], processing" ms.assetid: 60c71193-9dac-4cd3-98c5-100bd0edcc42 --- -# Processing the XML file (C# programming guide) +# Process the XML file (C# programming guide) -The compiler generates an ID string for each construct in your code that is tagged to generate documentation. (For information about how to tag your code, see [Recommended Tags for Documentation Comments](./recommended-tags-for-documentation-comments.md).) The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET Framework metadata/reflection item that the documentation applies to. +The compiler generates an ID string for each construct in your code that's tagged to generate documentation. (For information about how to tag your code, see [Recommended Tags for Documentation Comments](./recommended-tags-for-documentation-comments.md).) The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET metadata or reflection item that the documentation applies to. -The XML file is not a hierarchical representation of your code; it is a flat list that has a generated ID for each element. +## ID strings + +The XML file is not a hierarchical representation of your code. It's a flat list that has a generated ID for each element. The compiler observes the following rules when it generates the ID strings: - No white space is in the string. -- The first part of the ID string identifies the kind of member being identified, by way of a single character followed by a colon. The following member types are used: +- The first part of the string identifies the kind of member using a single character followed by a colon. The following member types are used: - |Character|Description| - |---------------|-----------------| - |N|namespace

You cannot add documentation comments to a namespace, but you can make cref references to them, where supported.| - |T|type: class, interface, struct, enum, or delegate| + |Character|Member type|Notes| + |---------------|-----------------|-| + |N|namespace|You cannot add documentation comments to a namespace, but you can make cref references to them, where supported.| + |T|type|A type can be a class, interface, struct, enum, or delegate.| |F|field| - |P|property (including indexers or other indexed properties)| - |M|method (including such special methods as constructors, operators, and so forth)| + |P|property|Includes indexers or other indexed properties.| + |M|method|Includes special methods, such as constructors and operators.| |E|event| - |!|error string

The rest of the string provides information about the error. The C# compiler generates error information for links that cannot be resolved.| + |!|error string|The rest of the string provides information about the error. The C# compiler generates error information for links that cannot be resolved.| -- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they are replaced by the hash-sign ('#'). It is assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the String constructor would be "System.String.#ctor". +- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they are replaced by the hash-sign ('#'). It's assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the String constructor is "System.String.#ctor". -- For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. The encoding of each argument follows directly how it is encoded in a .NET Framework signature: +- For properties and methods, the parameter list enclosed in parentheses follows. If there are no parameters, no parentheses are present. The parameters are separated by commas. The encoding of each parameter follows directly how it's encoded in a .NET signature: - Base types. Regular types (ELEMENT_TYPE_CLASS or ELEMENT_TYPE_VALUETYPE) are represented as the fully qualified name of the type. @@ -50,11 +52,11 @@ The compiler observes the following rules when it generates the ID strings: - ELEMENT_TYPE_GENERICARRAY is represented as "[?]" following the element type of the array. The C# compiler never generates this. - - ELEMENT_TYPE_ARRAY is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it is simply omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:]. + - ELEMENT_TYPE_ARRAY is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it's omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:]. - ELEMENT_TYPE_FNPTR is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The C# compiler never generates this. - The following signature components are not represented because they are never used for differentiating overloaded methods: + The following signature components aren't represented because they aren't used to differentiate overloaded methods: - calling convention @@ -62,17 +64,17 @@ The compiler observes the following rules when it generates the ID strings: - ELEMENT_TYPE_SENTINEL -- For conversion operators only (op_Implicit and op_Explicit), the return value of the method is encoded as a '~' followed by the return type, as encoded above. +- For conversion operators only (`op_Implicit` and `op_Explicit`), the return value of the method is encoded as a '~' followed by the return type. - For generic types, the name of the type is followed by a backtick and then a number that indicates the number of generic type parameters. For example: ```` is the tag for a type that is defined as `public class SampleClass`. - For methods taking generic types as parameters, the generic type parameters are specified as numbers prefaced with backticks (for example \`0,\`1). Each number representing a zero-based array notation for the type's generic parameters. + For methods that take generic types as parameters, the generic type parameters are specified as numbers prefaced with backticks (for example \`0,\`1). Each number represents a zero-based array notation for the type's generic parameters. ## Examples -The following examples show how the ID strings for a class and its members would be generated: +The following examples show how the ID strings for a class and its members are generated: [!code-csharp[csProgGuidePointers#21](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuidePointers/CS/Pointers.cs#21)] diff --git a/docs/csharp/programming-guide/xmldoc/remarks.md b/docs/csharp/programming-guide/xmldoc/remarks.md index b18fe0cfa78f9..42d81447ba40b 100644 --- a/docs/csharp/programming-guide/xmldoc/remarks.md +++ b/docs/csharp/programming-guide/xmldoc/remarks.md @@ -25,7 +25,7 @@ ms.assetid: f8641391-31f3-4735-af7a-c502a5b6a251 ## Remarks -The \ tag is used to add information about a type, supplementing the information specified with [\](./summary.md). This information is displayed in the Object Browser window. +The `` tag is used to add information about a type, supplementing the information specified with [\](./summary.md). This information is displayed in the Object Browser window. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/returns.md b/docs/csharp/programming-guide/xmldoc/returns.md index 3f21cb90a398b..dcf6c0e333180 100644 --- a/docs/csharp/programming-guide/xmldoc/returns.md +++ b/docs/csharp/programming-guide/xmldoc/returns.md @@ -25,7 +25,7 @@ ms.assetid: bb2d9958-62fc-47c7-9511-6311171f119f ## Remarks -The \ tag should be used in the comment for a method declaration to describe the return value. +The `` tag should be used in the comment for a method declaration to describe the return value. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/see.md b/docs/csharp/programming-guide/xmldoc/see.md index d387f9929c79c..cdbdc15ae0b6d 100644 --- a/docs/csharp/programming-guide/xmldoc/see.md +++ b/docs/csharp/programming-guide/xmldoc/see.md @@ -27,11 +27,11 @@ ms.assetid: 0200de01-7e2f-45c4-9094-829d61236383 ## Remarks -The \ tag lets you specify a link from within text. Use [\](./seealso.md) to indicate that text should be placed in a See Also section. Use the [cref Attribute](./cref-attribute.md) to create internal hyperlinks to documentation pages for code elements. +The `` tag lets you specify a link from within text. Use [\](./seealso.md) to indicate that text should be placed in a See Also section. Use the [cref Attribute](./cref-attribute.md) to create internal hyperlinks to documentation pages for code elements. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. -The following example shows a \ tag within a summary section. +The following example shows a `` tag within a summary section. [!code-csharp[csProgGuideDocComments#12](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDocComments/CS/DocComments.cs#12)] diff --git a/docs/csharp/programming-guide/xmldoc/seealso.md b/docs/csharp/programming-guide/xmldoc/seealso.md index ab825edea122b..3823f1a600848 100644 --- a/docs/csharp/programming-guide/xmldoc/seealso.md +++ b/docs/csharp/programming-guide/xmldoc/seealso.md @@ -31,7 +31,7 @@ ms.assetid: 8e157f3f-f220-4fcf-9010-88905b080b18 ## Remarks -The \ tag lets you specify the text that you might want to appear in a See Also section. Use [\](./see.md) to specify a link from within text. +The `` tag lets you specify the text that you might want to appear in a See Also section. Use [\](./see.md) to specify a link from within text. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. diff --git a/docs/csharp/programming-guide/xmldoc/summary.md b/docs/csharp/programming-guide/xmldoc/summary.md index 276c5608df3c6..2b04c8cc841df 100644 --- a/docs/csharp/programming-guide/xmldoc/summary.md +++ b/docs/csharp/programming-guide/xmldoc/summary.md @@ -25,9 +25,9 @@ ms.assetid: b4c43d92-2067-4eac-a59a-d32f5248c08b ## Remarks -The \ tag should be used to describe a type or a type member. Use [\](./remarks.md) to add supplemental information to a type description. Use the [cref Attribute](./cref-attribute.md) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. +The `` tag should be used to describe a type or a type member. Use [\](./remarks.md) to add supplemental information to a type description. Use the [cref Attribute](./cref-attribute.md) to enable documentation tools such as [DocFX](https://dotnet.github.io/docfx/) and [Sandcastle](https://github.com/EWSoftware/SHFB) to create internal hyperlinks to documentation pages for code elements. -The text for the \ tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser Window. +The text for the `` tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser Window. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file. To create the final documentation based on the compiler-generated file, you can create a custom tool, or use a tool such as [DocFX](https://dotnet.github.io/docfx/) or [Sandcastle](https://github.com/EWSoftware/SHFB). diff --git a/docs/csharp/programming-guide/xmldoc/value.md b/docs/csharp/programming-guide/xmldoc/value.md index 8f0a48a80425c..16a6e776c61bc 100644 --- a/docs/csharp/programming-guide/xmldoc/value.md +++ b/docs/csharp/programming-guide/xmldoc/value.md @@ -24,7 +24,7 @@ ms.assetid: 08dbadaf-9ab6-43d9-9493-98e43bed199a ## Remarks -The \ tag lets you describe the value that a property represents. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a [\](./summary.md) tag for the new property. You should then manually add a \ tag to describe the value that the property represents. +The `` tag lets you describe the value that a property represents. When you add a property via code wizard in the Visual Studio .NET development environment, it adds a [\](./summary.md) tag for the new property. You should then manually add a `` tag to describe the value that the property represents. Compile with [-doc](../../language-reference/compiler-options/doc-compiler-option.md) to process documentation comments to a file.