Skip to content

Commit 6d20c91

Browse files
author
Ron Petrusha
authored
Changed cross-reference, fenced xml (#5544)
* Changed cross-reference, fenced xml * Addressed review comment * Removed '/'
1 parent 652caa3 commit 6d20c91

File tree

1 file changed

+56
-53
lines changed

1 file changed

+56
-53
lines changed

‎docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md‎

Lines changed: 56 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -11,58 +11,61 @@ The following sample provides a basic overview of a type that has been documente
1111

1212
## Example
1313
[!code-csharp[csProgGuideDocComments#15](../../../csharp/programming-guide/xmldoc/codesnippet/CSharp/how-to-use-the-xml-documentation-features_1.cs)]
14-
15-
**// This .xml file was generated with the previous code sample.**
16-
**\<?xml version="1.0"?>**
17-
**\<doc>**
18-
**\<assembly>**
19-
**\<name>xmlsample\</name>**
20-
**\</assembly>**
21-
**\<members>**
22-
**\<member name="T:SomeClass">**
23-
**\<summary>**
24-
**Class level summary documentation goes here.\</summary>**
25-
**\<remarks>**
26-
**Longer comments can be associated with a type or member**
27-
**through the remarks tag\</remarks>**
28-
**\</member>**
29-
**\<member name="F:SomeClass.m_Name">**
30-
**\<summary>**
31-
**Store for the name property\</summary>**
32-
**\</member>**
33-
**\<member name="M:SomeClass.#ctor">**
34-
**\<summary>The class constructor.\</summary>**
35-
**\</member>**
36-
**\<member name="M:SomeClass.SomeMethod(System.String)">**
37-
**\<summary>**
38-
**Description for SomeMethod.\</summary>**
39-
**\<param name="s"> Parameter description for s goes here\</param>**
40-
**\<seealso cref="T:System.String">**
41-
**You can use the cref attribute on any tag to reference a type or member**
42-
**and the compiler will check that the reference exists. \</seealso>**
43-
**\</member>**
44-
**\<member name="M:SomeClass.SomeOtherMethod">**
45-
**\<summary>**
46-
**Some other method. \</summary>**
47-
**\<returns>**
48-
**Return results are described through the returns tag.\</returns>**
49-
**\<seealso cref="M:SomeClass.SomeMethod(System.String)">**
50-
**Notice the use of the cref attribute to reference a specific method \</seealso>**
51-
**\</member>**
52-
**\<member name="M:SomeClass.Main(System.String[])">**
53-
**\<summary>**
54-
**The entry point for the application.**
55-
**\</summary>**
56-
**\<param name="args"> A list of command line arguments\</param>**
57-
**\</member>**
58-
**\<member name="P:SomeClass.Name">**
59-
**\<summary>**
60-
**Name property \</summary>**
61-
**\<value>**
62-
**A value tag is used to describe the property value\</value>**
63-
**\</member>**
64-
**\</members>**
65-
**\</doc>**
14+
15+
The example generates an .xml file with the following contents:
16+
17+
```xml
18+
<?xml version="1.0"?>
19+
<doc>
20+
<assembly>
21+
<name>xmlsample</name>
22+
</assembly>
23+
<members>
24+
<member name="T:SomeClass">
25+
<summary>
26+
Class level summary documentation goes here.</summary>
27+
<remarks>
28+
Longer comments can be associated with a type or member
29+
through the remarks tag</remarks>
30+
</member>
31+
<member name="F:SomeClass.m_Name">
32+
<summary>
33+
Store for the name property</summary>
34+
</member>
35+
<member name="M:SomeClass.#ctor">
36+
<summary>The class constructor.</summary>
37+
</member>
38+
<member name="M:SomeClass.SomeMethod(System.String)">
39+
<summary>
40+
Description for SomeMethod.</summary>
41+
<param name="s"> Parameter description for s goes here</param>
42+
<seealso cref="T:System.String">
43+
You can use the cref attribute on any tag to reference a type or member
44+
and the compiler will check that the reference exists. </seealso>
45+
</member>
46+
<member name="M:SomeClass.SomeOtherMethod">
47+
<summary>
48+
Some other method. </summary>
49+
<returns>
50+
Return results are described through the returns tag.</returns>
51+
<seealso cref="M:SomeClass.SomeMethod(System.String)">
52+
Notice the use of the cref attribute to reference a specific method </seealso>
53+
</member>
54+
<member name="M:SomeClass.Main(System.String[])">
55+
<summary>
56+
The entry point for the application.
57+
</summary>
58+
<param name="args"> A list of command line arguments</param>
59+
</member>
60+
<member name="P:SomeClass.Name">
61+
<summary>
62+
Name property </summary>
63+
<value>A value tag is used to describe the property value</value>
64+
</member>
65+
</members>
66+
</doc>
67+
```
68+
6669
## Compiling the Code
6770
To compile the example, type the following command line:
6871

@@ -75,7 +78,7 @@ The following sample provides a basic overview of a type that has been documente
7578

7679
- 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.
7780

78-
- Developers are free to create their own set of tags. There is a recommended set of tags (see the Further Reading section). Some of the recommended tags have special meanings:
81+
- Developers are free to create their own set of tags. There is a recommended set of tags (see [Recommended tags for documentation comments](recommended-tags-for-documentation-comments.md)). Some of the recommended tags have special meanings:
7982

8083
- 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 failed, the compiler issues a warning.
8184

0 commit comments

Comments
 (0)