IT. Expert System.

C#

Recommended tags


The documentation generator must accept and process any tag that is valid according to the rules of XML. The following tags provide commonly used functionality in user documentation. (Of course, other tags are possible.)


Tag

Section

Purpose

<c>

A.2.1

Set text in a code-like font

<code>

A.2.2

Set one or more lines of source code or program output

<example>

A.2.3

Indicate an example

<exception>

A.2.4

Identifies the exceptions a method can throw

<include>

A.2.5

Includes XML from an external file

<list>

A.2.6

Create a list or table

<para>

A.2.7

Permit structure to be added to text

<param>

A.2.8

Describe a parameter for a method or constructor

<paramref>

A.2.9

Identify that a word is a parameter name

<permission>

A.2.10

Document the security accessibility of a member

<summary>

A.2.11

Describe a type

<returns>

A.2.12

Describe the return value of a method

<see>

A.2.13

Specify a link

<seealso>

A.2.14

Generate a See Also entry

<summary>

A.2.15

Describe a member of a type

<value>

A.2.16

Describe a property

<typeparam>


Describe a generic type parameter

<typeparamref>


Identify that a word is a type parameter name


      1. <c>

This tag provides a mechanism to indicate that a fragment of text within a description should be set in a special font such as that used for a block of code. For lines of actual code, use <code> .

Syntax:

<c>text</c>

Example:

/// <summary>Class <c>Point</c> models a point in a two-dimensional
/// plane.</summary>

public class Point
{
// ...
}

      1. <code>

This tag is used to set one or more lines of source code or program output in some special font. For small code fragments in narrative, use <c> .

Syntax:

<code>source code or program output</code>

Example:

/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// <example>For example:
/// <code>
/// Point p = new Point(3,5);
/// p.Translate(-1,3);
/// </code>
/// results in <c>p</c>'s having the value (2,8).
/// </example>
/// </summary>

public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

      1. <example>

This tag allows example code within a comment, to specify how a method or other library member may be used. Ordinarily, this would also involve use of the tag <code> as well.

Syntax:

<example>description</example>

Example:

See <code> (§A.2.2) for an example.

      1. <exception>

This tag provides a way to document the exceptions a method can throw.

Syntax:

<exception cref="member">description</exception>

where

cref="member"

The name of a member. The documentation generator checks that the given member exists and translates member to the canonical element name in the documentation file.

description

A description of the circumstances in which the exception is thrown.

Example:

public class DataBaseOperations
{
/// <exception cref="MasterFileFormatCorruptException"></exception>
/// <exception cref="MasterFileLockedOpenException"></exception>
public static void ReadRecord(int flag) {
if (flag == 1)
throw new MasterFileFormatCorruptException();
else if (flag == 2)
throw new MasterFileLockedOpenException();
// …
}
}

      1. <include>

This tag allows including information from an XML document that is external to the source code file. The external file must be a well-formed XML document, and an XPath expression is applied to that document to specify what XML from that document to include. The <include> tag is then replaced with the selected XML from the external document.

Syntax:

<include file="filename" path="xpath" />

where

file="filename"

The file name of an external XML file. The file name is interpreted relative to the file that contains the include tag.

path="xpath"

An XPath expression that selects some of the XML in the external XML file.

Example:

If the source code contained a declaration like:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { … }

and the external file “docs.xml” had the following contents:

<?xml version="1.0"?>
<extradoc>
<class name=
"IntList">
<summary>
Contains a list of integers.
</summary>
</class>
<class name=
"StringList">
<summary>
Contains a list of integers.
</summary>
</class>
</extradoc>

then the same documentation is output as if the source code contained:

/// <summary>
/// Contains a list of integers.
/// </summary>
public class IntList { … }

      1. <list>

This tag is used to create a list or table of items. It may contain a <listheader> block to define the heading row of either a table or definition list. (When defining a table, only an entry for term in the heading need be supplied.)

Each item in the list is specified with an <item> block. When creating a definition list, both term and description must be specified. However, for a table, bulleted list, or numbered list, only description need be specified.

Syntax:

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

<item>
<term>term</term>
<description>description</description>
</item>
</list>

where

term

The term to define, whose definition is in description.

description

Either an item in a bullet or numbered list, or the definition of a term.

Example:

public class MyClass
{
/// <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>
public static void Main () {
// ...
}
}

      1. <para>

This tag is for use inside other tags, such as <summary> or <returns> , and permits structure to be added to text.

Syntax:

<para>content</para>

where

content

The text of the paragraph.

Example:

/// <summary>This is the entry point of the Point class testing program.
/// <para>This program tests each method and operator, and
/// is intended to be run after any non-trvial maintenance has
/// been performed on the Point class.</para></summary>
public static void Main() {
// ...
}

      1. <param>

This tag is used to describe a parameter for a method, constructor, or indexer.

Syntax:

<param name="name">description</param>

where

name

The name of the parameter.

description

A description of the parameter.

Example:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <param name="xor">the new x-coordinate.</param>
/// <param name="yor">the new y-coordinate.</param>
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}

      1. <paramref>

This tag is used to indicate that a word is a parameter. The documentation file can be processed to format this parameter in some distinct way.

Syntax:

<paramref name="name"/>

where

name

The name of the parameter.

Example:

/// <summary>This constructor initializes the new Point to
/// (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param name="xor">the new Point's x-coordinate.</param>
/// <param name="yor">the new Point's y-coordinate.</param>

public Point(int xor, int yor) {
X = xor;
Y = yor;
}

      1. <permission>

This tag allows the security accessibility of a member to be documented.

Syntax:

<permission cref="member">description</permission>

where

cref="member"

The name of a member. The documentation generator checks that the given code element exists and translates member to the canonical element name in the documentation file.

description

A description of the access to the member.

Example:

/// <permission cref="System.Security.PermissionSet">Everyone can
/// access this method.</permission>

public static void Test() {
// ...
}

      1. <summary>

This tag is used to specify overview information about a type. (Use <summary> to describe the members of a type.)

Syntax:

<summary>description</summary>

where

description

The text of the summary.

Example:

/// <summary>Class <c>Point</c> models a point in a
/// two-dimensional plane.</summary>
public class Point
{
// ...
}

      1. <returns>

This tag is used to describe the return value of a method.

Syntax:

<returns>description</returns>

where

description

A description of the return value.

Example:

/// <summary>Report a point's location as a string.</summary>
/// <returns>A string representing a point's location, in the form (x,y),
/// without any leading, trailing, or embedded whitespace.</returns>
public override string ToString() {
return "(" + X + "," + Y + ")";
}

      1. <see>

This tag allows a link to be specified within text. Use <seealso> to indicate text that is to appear in a See Also section.

Syntax:

<see cref="member"/>

where

cref="member"

The name of a member. The documentation generator checks that the given code element exists and changes member to the element name in the generated documentation file.

Example:

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <see cref="Translate"/>
public void Move(int xor, int yor) {
X = xor;
Y = yor;
}

/// <summary>This method changes the point's location by
/// the given x- and y-offsets.
/// </summary>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

      1. <seealso>

This tag allows an entry to be generated for the See Also section. Use <see> to specify a link from within text.

Syntax:

<seealso cref="member"/>

where

cref="member"

The name of a member. The documentation generator checks that the given code element exists and changes member to the element name in the generated documentation file.

Example:

/// <summary>This method determines whether two Points have the same
/// location.</summary>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o) {
// ...
}

      1. <summary>

This tag can be used to describe a member for a type. Use <summary> to describe the type itself.

Syntax:

<summary>description</summary>

where

description

A summary of the member.

Example:

/// <summary>This constructor initializes the new Point to (0,0).</summary>
public Point() : this(0,0) {
}

      1. <value>

This tag allows a property to be described.

Syntax:

<value>property description</value>

where

property description

A description for the property.

Example:

/// <value>Property <c>X</c> represents the point's x-coordinate.</value>
public int X
{
get { return x; }
set { x = value; }
}

      1. <typeparam>

This tag is used to describe a generic type parameter for a class, struct, interface, delegate, or method.

Syntax:

<typeparam name="name">description</typeparam>

where

name

The name of the type parameter.

description

A description of the type parameter.

Example:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T> {
...
}

      1. <typeparamref>

This tag is used to indicate that a word is a type parameter. The documentation file can be processed to format this type parameter in some distinct way.

Syntax:

<typeparamref name="name"/>

where

name

The name of the type parameter.

Example:

/// <summary>This method fetches data and returns a list of <typeparamref name=”T”> ”/>”> .</summary>
/// <param name="string">query to execute</param>

public List<T> FetchData<T>(string query) {
...
}



Content

Android Reference

Java basics

Java Enterprise Edition (EE)

Java Standard Edition (SE)

SQL

HTML

PHP

CSS

Java Script

MYSQL

JQUERY

VBS

REGEX

C

C++

C#

Design patterns

RFC (standard status)

RFC (proposed standard status)

RFC (draft standard status)

RFC (informational status)

RFC (experimental status)

RFC (best current practice status)

RFC (historic status)

RFC (unknown status)

IT dictionary

License.
All information of this service is derived from the free sources and is provided solely in the form of quotations. This service provides information and interfaces solely for the familiarization (not ownership) and under the "as is" condition.
Copyright 2016 © ELTASK.COM. All rights reserved.
Site is optimized for mobile devices.
Downloads: 75 / . Delta: 0.02857 с