Csharp/CSharp Tutorial/Language Basics/Documentation Comments — различия между версиями
Admin (обсуждение | вклад) м (1 версия) |
|
(нет различий)
|
Текущая версия на 15:19, 26 мая 2010
Содержание
- 1 Compiler Support Tags
- 2 Documentation Comments for A member variable
- 3 Documentation Comments for a method with parameters
- 4 Documentation Comments for A property
- 5 Documentation Comments for class
- 6 Documentation Comments for Main function
- 7 Recommended Code Comment XML Elements
- 8 XML Documentation
Compiler Support Tags
<source lang="csharp">using System; namespace Payroll {
/// <summary> /// Document for Employee class /// See a cross reference <see cref="String">string</see> /// </summary> public class Employee { /// <summary> /// Comment for the constructor /// <paramref name="name">name2</paramref> is a string. /// </summary> /// <param name="id">Employee id number</param> /// <param name="name">Employee Name</param> public Employee(int id, string name) { this.id = id; this.name = name; } /// <summary> /// Comments for another constructor /// </summary> /// <remarks> /// <seealso cref="Employee(int, string)">Employee(int, string)</seealso> /// </remarks> public Employee() { id = -1; name = null; } int id; string name; }
}</source>
Documentation Comments for A member variable
<source lang="csharp">using System; namespace DocumentationCommentsExample {
/// <summary> /// A documentation sample - the short description goes here /// </summary> /// <remarks>Where a longer description would go</remarks> class ClassExample { /// <summary> /// A member variable /// </summary> private string m_str; }
}</source>
Documentation Comments for a method with parameters
<source lang="csharp">using System; namespace DocumentationCommentsExample {
/// <summary> /// A documentation sample - the short description goes here /// </summary> /// <remarks>Where a longer description would go</remarks> class ClassExample { /// <summary> /// A member variable /// </summary> private string m_str;
/// <summary> /// A method example /// </summary> /// <param name="val">a new value to be saved</param> /// <returns>the length of the string</returns> public int MethodExample( string val ) { m_str = val; return val.Length; } }
}</source>
Documentation Comments for A property
<source lang="csharp">using System; namespace DocumentationCommentsExample {
/// <summary> /// A documentation sample - the short description goes here /// </summary> /// <remarks>Where a longer description would go</remarks> class ClassExample { /// <summary> /// A member variable /// </summary> private string m_str;
/// <summary> /// A property example /// </summary> /// <remarks> /// You would put a more in depth description inside remarks tags /// </remarks> public string PropertyExample { get { return m_str; } } }
}</source>
Documentation Comments for class
<source lang="csharp">using System; namespace DocumentationCommentsExample {
/// <summary> /// A documentation sample - the short description goes here /// </summary> /// <remarks>Where a longer description would go</remarks> class ClassExample { }
}</source>
Documentation Comments for Main function
<source lang="csharp">using System; namespace DocumentationCommentsExample {
/// <summary> /// A documentation sample - the short description goes here /// </summary> /// <remarks>Where a longer description would go</remarks> class ClassExample { /// <summary> /// The main method for the program /// </summary> /// <param name="args">command line arguments</param> static void Main(string[] args) { }
}
}</source>
Recommended Code Comment XML Elements
<source lang="csharp">Predefined XML Element Meaning in Life
<c> code font
Indicates multiple lines should be marked as code
<example> Mocks up a code example
<exception> Documents which exceptions a given class may throw
<list> Inserts a list or table into the documentation file
<param> Describes a given parameter
<paramref> Associates a given XML tag with a specific parameter
<permission> Documents the security constraints for a given member
<remarks> Builds a description for a given member
<returns> Documents the return value of the member
<see> Cross-references related items in the document
<seealso> Builds an "also see" section within a description
<summary> Documents the "executive summary" for a given member
<value> Documents a given property</source>
XML Documentation
<source lang="csharp">Tag Description <c> Marks up text within a line as code, for example: <c>int i = 10;</c> <code> Marks multiple lines as code. <example> Marks up a code example. <exception> Documents an exception class. (Syntax verified by the compiler.) <include> Includes comments from another documentation file. (Syntax verified by the compiler.) <list> Inserts a list into the documentation. <param> Marks up a method parameter. (Syntax verified by the compiler.) <paramref> Indicates that a word is a method parameter. (Syntax verified by the compiler.) <permission> Documents access to a member. (Syntax verified by the compiler.) <remarks> Adds a description for a member. <returns> Documents the return value for a method. <see> Provides a cross-reference to another parameter. (Syntax verified by the compiler.) <seealso> Provides a "see also" section in a description. (Syntax verified by the compiler.) <summary> Provides a short summary of a type or member. <value> Describes a property.</source>