Skip to content

Changed cross-reference, fenced xml #5544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 22, 2018
Merged

Changed cross-reference, fenced xml #5544

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b3db7e9
Changed cross-reference, fenced xml
May 22, 2018
f83a261
Addressed review comment
May 22, 2018
2ec69f1
Removed '/'
May 22, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 56 additions & 53 deletions docs/csharp/programming-guide/xmldoc/how-to-use-the-xml-documentation-features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,58 +11,61 @@ The following sample provides a basic overview of a type that has been documente

## Example
[!code-csharp[csProgGuideDocComments#15](../../../csharp/programming-guide/xmldoc/codesnippet/CSharp/how-to-use-the-xml-documentation-features_1.cs)]

**// This .xml file was generated with the previous code sample.**
**\<?xml version="1.0"?>**
**\<doc>**
**\<assembly>**
**\<name>xmlsample\</name>**
**\</assembly>**
**\<members>**
**\<member name="T:SomeClass">**
**\<summary>**
**Class level summary documentation goes here.\</summary>**
**\<remarks>**
**Longer comments can be associated with a type or member**
**through the remarks tag\</remarks>**
**\</member>**
**\<member name="F:SomeClass.m_Name">**
**\<summary>**
**Store for the name property\</summary>**
**\</member>**
**\<member name="M:SomeClass.#ctor">**
**\<summary>The class constructor.\</summary>**
**\</member>**
**\<member name="M:SomeClass.SomeMethod(System.String)">**
**\<summary>**
**Description for SomeMethod.\</summary>**
**\<param name="s"> Parameter description for s goes here\</param>**
**\<seealso cref="T:System.String">**
**You can use the cref attribute on any tag to reference a type or member**
**and the compiler will check that the reference exists. \</seealso>**
**\</member>**
**\<member name="M:SomeClass.SomeOtherMethod">**
**\<summary>**
**Some other method. \</summary>**
**\<returns>**
**Return results are described through the returns tag.\</returns>**
**\<seealso cref="M:SomeClass.SomeMethod(System.String)">**
**Notice the use of the cref attribute to reference a specific method \</seealso>**
**\</member>**
**\<member name="M:SomeClass.Main(System.String[])">**
**\<summary>**
**The entry point for the application.**
**\</summary>**
**\<param name="args"> A list of command line arguments\</param>**
**\</member>**
**\<member name="P:SomeClass.Name">**
**\<summary>**
**Name property \</summary>**
**\<value>**
**A value tag is used to describe the property value\</value>**
**\</member>**
**\</members>**
**\</doc>**

The example generates an .xml file with the following contents:

```xml
<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:SomeClass">
<summary>
Class level summary documentation goes here.</summary>
<remarks>
Longer comments can be associated with a type or member
through the remarks tag</remarks>
</member>
<member name="F:SomeClass.m_Name">
<summary>
Store for the name property</summary>
</member>
<member name="M:SomeClass.#ctor">
<summary>The class constructor.</summary>
</member>
<member name="M:SomeClass.SomeMethod(System.String)">
<summary>
Description for SomeMethod.</summary>
<param name="s"> Parameter description for s goes here</param>
<seealso cref="T:System.String">
You can use the cref attribute on any tag to reference a type or member
and the compiler will check that the reference exists. </seealso>
</member>
<member name="M:SomeClass.SomeOtherMethod">
<summary>
Some other method. </summary>
<returns>
Return results are described through the returns tag.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)">
Notice the use of the cref attribute to reference a specific method </seealso>
</member>
<member name="M:SomeClass.Main(System.String[])">
<summary>
The entry point for the application.
</summary>
<param name="args"> A list of command line arguments</param>
</member>
<member name="P:SomeClass.Name">
<summary>
Name property </summary>
<value>A value tag is used to describe the property value</value>
</member>
</members>
</doc>
```

## Compiling the Code
To compile the example, type the following command line:

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

- 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 (see the Further Reading section). 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 [Recommended tags for documentation comments](recommended-tags-for-documentation-comments.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 failed, the compiler issues a warning.

Expand Down