Code documentation

From wiki.techunit.org
Jump to: navigation, search

Tags

c

This tag gives you a way to indicate that text within a description should be marked as code.

/// <summary>
///    <c>DoWork</c> is a method in the <c>TestClass</c> class.
/// </summary>
public static void DoWork(int Int1) { }

code

This tag gives you a way to indicate multiple lines as code.
See 'example' tag for usage

example

This tag lets you specify an example of how to use a method or other library member

/// <summary> The GetZero method. </summary>
/// <example> 
///     This sample shows how to call the <see cref="GetZero"/> method.
///     <code>
///         class TestClass 
///         {
///             static int Main() { return GetZero(); }
///         }
///     </code>
/// </example>
public static int GetZero() { return 0; }

exception

This tag lets you specify which exceptions can be thrown.This tag can be applied to definitions for methods, properties, events, and indexers.

/// <exception cref="System.Exception">Thrown when...</exception>
public void DoSomething()
{
    try { }
    catch (EClass) { }
}

include

This 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.

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />
class Test
{
    static void Main() { }
}

/// <include file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />
class Test2
{
    public void Test() { }
}

Example of included XML file:

<MyDocs>
    <MyMembers name="test">
        <summary> The summary for this type. </summary>
    </MyMembers>
    <MyMembers name="test2">
        <summary> The summary for this other type. </summary>
    </MyMembers>
</MyDocs>

list

The <listheader> 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 <item> 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 <item> blocks as needed.

Usage :

<list type='("bullet" | "number" | "table")'>
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

Example:

/// <summary>
///     Here is an example of a bulleted list:
///     <list type="bullet">
///         <item>
///             <description>Item 1.</description>
///         </item>
///         <item>
///             <description>Item 2.</description>
///         </item>
///     </list>
/// </summary>
static void Main() { }

para

This tag is for use inside a tag, such as "summary", "remarks", or "returns", and lets you add structure to the text.
See "summary" for an example of using "para".

param

This 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 "param" tags.
The text for the "param" tag will be displayed in IntelliSense, the Object Browser, and in the Code Comment Web Report.

/// <param name="Int1"> Used to indicate status. </param>
/// <param name="Float1"> Used to specify context. </param>
public static void DoWork(int Int1, float Float1) { }

paramref

This tag gives you a way to indicate that a word in the code comments, for example in a "summary" or "remarks" 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.

/// <summary>
///     DoWork is a method in the TestClass class.  
///     The <paramref name="Int1"/> parameter takes a number.
/// </summary>
public static void DoWork(int Int1) { }

permission

The <permission> tag lets you document the access of a member.
The PermissionSet class lets you specify access to a member.
For information on how to create a cref reference to a generic type, refer to "see" tag

/// <permission cref="System.Security.PermissionSet">
///     Everyone can access this method.
/// </permission>
public static void Test() { }

remarks

This tag is used to add information about a type, supplementing the information specified with <summary>. This information is displayed in the Object Browser Window.

/// <summary> You may have some primary information about this class. </summary>
/// <remarks> You may have some additional information about this class. </remarks>
public class TestClass { }

returns

This tag should be used in the comment for a method declaration to describe the return value.

/// <returns> Returns zero. </returns>
public static int GetZero() { return 0; }

see

This tag lets you specify a link from within text.Use <seealso> to indicate that text should be placed in a See Also section.
Use the cref Attribute to create internal hyperlinks to documentation pages for code elements.

/// <summary>
///     DoWork is a method in the TestClass class.
///     <para>
///         Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.
///     </para>
///     <seealso cref="TestClass.Main"/>
/// </summary>
public static void DoWork(int Int1) { }

seealso

This tag lets you specify the text that you might want to appear in a See Also section.
Use "see" to specify a link from within text.

summary

This tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description.
Use the cref Attribute to enable documentation tools such as Sandcastle to create internal hyperlinks to documentation pages for code elements.
The text for the "summary" tag is the only source of information about the type in IntelliSense, and is also displayed in the Object Browser Window.

/// <summary>
///     DoWork is a method in the TestClass class.
///     <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
///     <seealso cref="TestClass.Main"/>
/// </summary>
public static void DoWork(int Int1) { }

With cref usage: See https://msdn.microsoft.com/fr-fr/library/2d6dt3kf.aspx

typeparam

This tag should be used in the comment for a generic type or method declaration to describe a type parameter.
Add a tag for each type parameter of the generic type or method.

/// <summary>
///     Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T"> The element type of the array </typeparam>
public static T[] mkArray<T>(int n) { return new T[n]; }

typeparamref

Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics

/// <summary>
///     Creates a new array of arbitrary type <typeparamref name="T"/>
/// </summary>
/// <typeparam name="T"> The element type of the array </typeparam>
public static T[] mkArray<T>(int n) { return new T[n]; }

value

This 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" tag for the new property.You should then manually add a "value" tag to describe the value that the property represents.

/// <summary> The Name property represents the employee's name. </summary>
/// <value> The Name property gets/sets the value of the string field, _name. </value>
public string Name
{
    get { return _name; }
    set { _name = value; }
}

Sources

https://msdn.microsoft.com/fr-fr/library/5ast78ax.aspx