COM и Win32 12 страница

· аргументы, являющиеся массивами, представляются как [ нижняя_граница: размер, …, нижняя_граница: размер ], где число запятых равно рангу минус один, а нижние границы и размер каждого измерения, если они известны, представляются десятичными числами. Если нижняя граница или размер не указаны, они опускаются. Если для отдельного измерения опущены и нижняя граница, и размер, то «:» тоже опускается. Массивы массивов представлены одним «[]» на каждый уровень:

· аргументы, имеющие типы указателей, отличные от void, представляются с помощью * вслед за именем типа. Указатель типа void представляется с помощью имени типа System.Void;

· аргументы, ссылающиеся на параметры универсального типа, определенные для типов, кодируются с помощью символа «`», за которым следует начинающийся с нуля индекс параметра типа;

· аргументы, использующие параметры универсального типа, определенные в методах, используют двойной обратный апостроф «``» вместо одинарного «`», используемого для типов;

· аргументы, ссылающиеся на построенные универсальные типы, кодируются с помощью универсального типа, за которым следует «{», затем разделенный запятыми список аргументов типа и затем «}».

A.3.2 Примеры строк идентификаторов

В каждом из следующих примеров показан фрагмент кода на C# вместе со строками идентификаторов, созданных по каждому исходному элементу, для которого возможен комментарий к документации:

· типы представлены своими полными именами, дополненными общими сведениями:

enum Color { Red, Blue, Green }

namespace Acme
{
interface IProcess {...}

struct ValueType {...}

class Widget: IProcess
{
public class NestedClass {...}

public interface IMenuItem {...}

public delegate void Del(int i);

public enum Direction { North, South, East, West }
}

class MyList<T>
{
class Helper<U,V> {...}
}
}

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"
”T:Acme.MyList`1”
”T:Acme.MyList`1.Helper`2”

· поля представлены своими полными именами:

namespace Acme
{
struct ValueType
{
private int total;
}

class Widget: IProcess
{
public class NestedClass
{
private int value;
}

private string message;
private static Color defaultColor;
private const double PI = 3.14159;
protected readonly double monthlyAverage;
private long[] array1;
private Widget[,] array2;
private unsafe int *pCount;
private unsafe float **ppValues;
}
}

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"

· конструкторы;

namespace Acme
{
class Widget: IProcess
{
static Widget() {...}

public Widget() {...}

public Widget(string s) {...}
}
}

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

· деструкторы;

namespace Acme
{
class Widget: IProcess
{
~Widget() {...}
}
}

"M:Acme.Widget.Finalize"

· методы;

namespace Acme
{
struct ValueType
{
public void M(int i) {...}
}

class Widget: IProcess
{
public class NestedClass
{
public void M(int i) {...}
}

public static void M0() {...}
public void M1(char c, out float f, ref ValueType v) {...}
public void M2(short[] x1, int[,] x2, long[][] x3) {...}
public void M3(long[][] x3, Widget[][,,] x4) {...}
public unsafe void M4(char *pc, Color **pf) {...}
public unsafe void M5(void *pv, double *[][,] pd) {...}
public void M6(int i, params object[] args) {...}
}

class MyList<T>
{
public void Test(T t) { }
}

class UseList
{
public void Process(MyList<int> list) { }
public MyList<T> GetValues<T>(T inputValue) { return null; }
}
}

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"
”M:Acme.MyList`1.Test(`0)”
”M:Acme.UseList.Process(Acme.MyList{System.Int32})”
”M:Acme.UseList.GetValues``(``0)”

· свойства и индексаторы;

namespace Acme
{
class Widget: IProcess
{
public int Width { get {...} set {...} }
public int this[int i] { get {...} set {...} }
public int this[string s, int i] { get {...} set {...} }
}
}

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

· события;

namespace Acme
{
class Widget: IProcess
{
public event Del AnEvent;
}
}

"E:Acme.Widget.AnEvent"

· унарные операторы;

namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x) {...}
}
}

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"

Полный набор имен функций унарных операторов следующий: op_UnaryPlus, op_UnaryNegation, op_LogicalNot, op_OnesComplement, op_Increment, op_Decrement, op_True и op_False.

· бинарные операторы;

namespace Acme
{
class Widget: IProcess
{
public static Widget operator+(Widget x1, Widget x2) {...}
}
}

"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

Полный набор имен функций двоичных операторов следующий: op_Addition, op_Subtraction, op_Multiply, op_Division, op_Modulus, op_BitwiseAnd, op_BitwiseOr, op_ExclusiveOr, op_LeftShift, op_RightShift, op_Equality, op_Inequality, op_LessThan, op_LessThanOrEqual, op_GreaterThan и op_GreaterThanOrEqual.

· операторы преобразования оканчиваются символом "~", за которым следует тип возвращаемого значения;

namespace Acme
{
class Widget: IProcess
{
public static explicit operator int(Widget x) {...}
public static implicit operator long(Widget x) {...}
}
}

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"

A.4 Пример

A.4.1 Исходный код C#

В следующем примере показан исходный код класса Point:

namespace Graphics
{

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

/// <summary>Instance variable <c>x</c> represents the point's
/// x-coordinate.</summary>
private int x;

/// <summary>Instance variable <c>y</c> represents the point's
/// y-coordinate.</summary>
private int y;

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

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

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

/// <summary>This constructor initializes the new Point to
/// (<paramref name="xor"/>,<paramref name="yor"/>).</summary>
/// <param><c>xor</c> is the new Point's x-coordinate.</param>
/// <param><c>yor</c> is the new Point's y-coordinate.</param>
public Point(int xor, int yor) {
X = xor;
Y = yor;
}

/// <summary>This method changes the point's location to
/// the given coordinates.</summary>
/// <param><c>xor</c> is the new x-coordinate.</param>
/// <param><c>yor</c> is the new y-coordinate.</param>
/// <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.
/// <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>
/// <param><c>xor</c> is the relative x-offset.</param>
/// <param><c>yor</c> is the relative y-offset.</param>
/// <see cref="Move"/>
public void Translate(int xor, int yor) {
X += xor;
Y += yor;
}

/// <summary>This method determines whether two Points have the same
/// location.</summary>
/// <param><c>o</c> is the object to be compared to the current object.
/// </param>
/// <returns>True if the Points have the same location and they have
/// the exact same type; otherwise, false.</returns>
/// <seealso cref="operator=="/>
/// <seealso cref="operator!="/>
public override bool Equals(object o) {
if (o == null) {
return false;
}

if (this == o) {
return true;
}

if (GetType() == o.GetType()) {
Point p = (Point)o;
return (X == p.X) && (Y == p.Y);
}
return false;
}

/// <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, training, or embedded whitespace.</returns>
public override string ToString() {
return "(" + X + "," + Y + ")";
}

/// <summary>This operator determines whether two Points have the same
/// location.</summary>
/// <param><c>p1</c> is the first Point to be compared.</param>
/// <param><c>p2</c> is the second Point to be compared.</param>
/// <returns>True if the Points have the same location and they have
/// the exact same type; otherwise, false.</returns>
/// <seealso cref="Equals"/>
/// <seealso cref="operator!="/>
public static bool operator==(Point p1, Point p2) {
if ((object)p1 == null || (object)p2 == null) {
return false;
}

if (p1.GetType() == p2.GetType()) {
return (p1.X == p2.X) && (p1.Y == p2.Y);
}

return false;
}

/// <summary>This operator determines whether two Points have the same
/// location.</summary>
/// <param><c>p1</c> is the first Point to be compared.</param>
/// <param><c>p2</c> is the second Point to be compared.</param>
/// <returns>True if the Points do not have the same location and the
/// exact same type; otherwise, false.</returns>
/// <seealso cref="Equals"/>
/// <seealso cref="operator=="/>
public static bool operator!=(Point p1, Point p2) {
return!(p1 == p2);
}

/// <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() {
// class test code goes here
}
}
}

A.4.2 Результирующий XML

Здесь представлен результат, созданный генератором документации по вышеприведенному исходному коду для класса Point:

<?xml version="1.0"?>
<doc>
<assembly>
<name>Point</name>
</assembly>
<members>
<member name="T:Graphics.Point">
<summary>Class <c>Point</c> models a point in a two-dimensional
plane.
</summary>
</member>

<member name="F:Graphics.Point.x">
<summary>Instance variable <c>x</c> represents the point's
x-coordinate.</summary>
</member>

<member name="F:Graphics.Point.y">
<summary>Instance variable <c>y</c> represents the point's
y-coordinate.</summary>
</member>

<member name="M:Graphics.Point.#ctor">
<summary>This constructor initializes the new Point to
(0,0).</summary>
</member>

<member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
<summary>This constructor initializes the new Point to
(<paramref name="xor"/>,<paramref name="yor"/>).</summary>
<param><c>xor</c> is the new Point's x-coordinate.</param>
<param><c>yor</c> is the new Point's y-coordinate.</param>
</member>

<member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
<summary>This method changes the point's location to
the given coordinates.</summary>
<param><c>xor</c> is the new x-coordinate.</param>
<param><c>yor</c> is the new y-coordinate.</param>
<see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
</member>

<member
name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
<summary>This method changes the point's location by
the given x- and y-offsets.
<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>
<param><c>xor</c> is the relative x-offset.</param>
<param><c>yor</c> is the relative y-offset.</param>
<see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
</member>

<member name="M:Graphics.Point.Equals(System.Object)">
<summary>This method determines whether two Points have the same
location.</summary>
<param><c>o</c> is the object to be compared to the current
object.
</param>
<returns>True if the Points have the same location and they have
the exact same type; otherwise, false.</returns>
<seealso
cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
<seealso
cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
</member>

<member name="M:Graphics.Point.ToString">
<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, training, or embedded whitespace.</returns>
</member>

<member
name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
<summary>This operator determines whether two Points have the
same
location.</summary>
<param><c>p1</c> is the first Point to be compared.</param>
<param><c>p2</c> is the second Point to be compared.</param>
<returns>True if the Points have the same location and they have
the exact same type; otherwise, false.</returns>
<seealso cref="M:Graphics.Point.Equals(System.Object)"/>
<seealso
cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
</member>

<member
name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
<summary>This operator determines whether two Points have the
same
location.</summary>
<param><c>p1</c> is the first Point to be compared.</param>
<param><c>p2</c> is the second Point to be compared.</param>
<returns>True if the Points do not have the same location and
the
exact same type; otherwise, false.</returns>
<seealso cref="M:Graphics.Point.Equals(System.Object)"/>
<seealso
cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
</member>

<member name="M:Graphics.Point.Main">
<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>
</member>

<member name="P:Graphics.Point.X">
<value>Property <c>X</c> represents the point's
x-coordinate.</value>
</member>

<member name="P:Graphics.Point.Y">
<value>Property <c>Y</c> represents the point's
y-coordinate.</value>
</member>
</members>
</doc>

B. Грамматика

Это приложение содержит сводные сведения о лексике и синтаксисе, используемых в основном документе, а также о грамматических расширениях для небезопасного кода. Грамматические конструкции отображаются здесь в том же порядке, в котором они представлены в основном документе.

Дата добавления: 2015-11-14