You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The use of documentation tags requires delimiters, which indicate to the compiler where a documentation comment begins and ends.
10
+
The use of documentation tags requires *delimiters*, which indicate to the compiler where a documentation comment begins and ends.
11
11
12
12
You can use the following kinds of delimiters with the XML documentation tags:
13
13
14
14
| Delimiter | Description |
15
-
|-|-|
16
-
|`///`| This is the form that is shown in documentation examples and used by the Visual Studio C++ project templates.|
17
-
|`/** */`| These are multiline delimiters.|
15
+
|--|--|
16
+
|`///`| This is the form that's shown in documentation examples and used by the Visual Studio C++ project templates. |
17
+
|`/** */`| These are multiline delimiters. |
18
18
19
19
There are some formatting rules when using the `/** */` delimiters:
20
20
21
-
- For the line that contains the `/**` delimiter, if the remainder of the line is white space, the line is not processed for comments. If the first character is white space, that white space character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment.
21
+
- For the line that contains the `/**` delimiter, if the rest of the line is whitespace, the line isn't processed for comments. If the first character is whitespace, that whitespace character is ignored and the rest of the line is processed. Otherwise, the entire text of the line after the `/**` delimiter is processed as part of the comment.
22
22
23
-
- For the line that contains the `*/` delimiter, if there is only white space up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment, subject to the pattern-matching rules described in the following bullet.
23
+
- For the line that contains the `*/` delimiter, if there's only whitespace up to the `*/` delimiter, that line is ignored. Otherwise, the text on the line up to the `*/` delimiter is processed as part of the comment, subject to the pattern-matching rules described in the following bullet.
24
24
25
-
- For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line that consists of optional white space and an asterisk (`*`), followed by more optional white space. If the compiler finds a common set of characters at the beginning of each line, it will ignore that pattern for all lines after the `/**` delimiter, up to and possibly including the line that contains the `*/` delimiter.
25
+
- For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line that consists of optional white space and an asterisk (`*`), followed by more optional whitespace. If the compiler finds a common set of characters at the beginning of each line, it will ignore that pattern for all lines after the `/**` delimiter, up to and possibly including the line that contains the `*/` delimiter.
26
26
27
-
Some examples:
27
+
## Examples
28
28
29
29
- The only part of the following comment that will be processed is the line that begins with `<summary>`. The following two tag formats will produce the same comments:
30
30
@@ -43,15 +43,15 @@ Some examples:
43
43
* text </summary>*/
44
44
```
45
45
46
-
- The compiler finds no pattern in this comment because there is no asterisk on the second line. Therefore, all text on the second and third lines, up till the `*/`, will be processed as part of the comment.
46
+
- The compiler finds no pattern in this comment because there's no asterisk on the second line. All text on the second and third lines, up until the `*/`, will be processed as part of the comment.
47
47
48
48
```cpp
49
49
/**
50
50
* <summary>
51
51
text </summary>*/
52
52
```
53
53
54
-
- The compiler finds no pattern in this comment for two reasons. First, there is no line that begins with a consistent number of spaces before the asterisk. Second, the fifth line begins with a tab, which does notmatch spaces. Therefore, all text from the second line until the `*/` will be processed as part of the comment.
54
+
- The compiler finds no pattern in this comment for two reasons. First, there's no line that begins with a consistent number of spaces before the asterisk. Second, the fifth line begins with a tab, which doesn't match spaces. All text from the second line until the `*/` will be processed as part of the comment.
Copy file name to clipboardExpand all lines: docs/build/reference/dot-xml-file-processing.md
+35-35Lines changed: 35 additions & 35 deletions
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,15 @@
1
1
---
2
-
description: "Learn more about: .Xml File Processing"
3
-
title: ".Xml File Processing"
4
-
ms.date: "11/04/2016"
2
+
description: "Learn more about: XML documentation file processing"
3
+
title: "XML documentation file processing"
4
+
ms.date: 12/03/2021
5
5
helpviewer_keywords: ["XML documentation, processing XML file"]
6
6
ms.assetid: e70fdeae-80ac-4872-ab24-771c5635cfbf
7
7
---
8
-
# .Xml File Processing
8
+
# XML documentation file processing
9
9
10
-
The compiler generates an ID string for each construct in your code that is tagged to generate documentation. For more information, see [Recommended Tags Documentation Comments](recommended-tags-for-documentation-comments-visual-cpp.md). The ID string uniquely identifies the construct. Programs that process the .xml file can use the ID string to identify the corresponding .NET Framework metadata or reflection item to which the documentation applies.
10
+
The compiler generates an ID string for each construct in your code that is tagged to generate documentation. For more information, see [Recommended tags documentation comments](recommended-tags-for-documentation-comments-visual-cpp.md). The ID string uniquely identifies the construct. Programs that process the XML file can use the ID string to identify the corresponding .NET Framework metadata or reflection item to which the documentation applies.
11
11
12
-
The .xml file is not a hierarchical representation of your code, it is a flat list with a generated ID for each element.
12
+
The XML file isn't a hierarchical representation of your code, it's a flat list with a generated ID for each element.
13
13
14
14
The compiler observes the following rules when it generates the ID strings:
15
15
@@ -19,60 +19,60 @@ The compiler observes the following rules when it generates the ID strings:
19
19
20
20
| Character | Description |
21
21
|---------------|-----------------|
22
-
| N |namespace<br /><br /> You cannot add documentation comments to a namespace, cref references to a namespace are possible. |
23
-
| T |type: class, interface, struct, enum, delegate |
24
-
| D |typedef|
25
-
| F |field|
26
-
| P |property (including indexers or other indexed properties) |
27
-
| M |method (including such special methods as constructors, operators, and so forth) |
28
-
| E |event|
29
-
| ! |error string<br /><br /> The rest of the string provides information about the error. The MSVC compiler generates error information for links that cannot be resolved. |
22
+
| N |Namespace<br /><br /> You can't add documentation comments to a namespace, cref references to a namespace are possible. |
23
+
| T |Type: class, interface, struct, enum, delegate |
24
+
| D |Typedef|
25
+
| F |Field|
26
+
| P |Property (including indexers or other indexed properties) |
27
+
| M |Method (including such special methods as constructors, operators, and so forth) |
28
+
| E |Event|
29
+
| ! |Error string<br /><br /> The rest of the string provides information about the error. The MSVC compiler generates error information for links that can't be resolved. |
30
30
31
-
- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type or types, and namespace are separated by periods. If the name of the item itself has periods, they are replaced by the hash-sign ('#'). It is assumed that no item has an hash-sign directly in its name. For example, the fully qualified name of the `String` constructor would be "System.String.#ctor".
31
+
- The second part of the string is the fully qualified name of the item, starting at the root of the namespace. The name of the item, its enclosing type or types, and namespace are separated by periods. If the name of the item itself has periods, they're replaced by the hash-sign ('#'). It's assumed that no item has a hash-sign directly in its name. For example, the fully qualified name of the `String` constructor would be `System.String.#ctor`.
32
32
33
-
- For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. The encoding of each argument follows directly how it is encoded in a .NET Framework signature:
33
+
- For properties and methods, if there are arguments to the method, the argument list enclosed in parentheses follows. If there are no arguments, no parentheses are present. The arguments are separated by commas. Each argument is encoded the same way it's encoded in a .NET Framework signature:
34
34
35
-
- Base types. Regular types (ELEMENT_TYPE_CLASS or ELEMENT_TYPE_VALUETYPE) are represented as the fully qualified name of the type.
35
+
- Base types. Regular types (`ELEMENT_TYPE_CLASS` or `ELEMENT_TYPE_VALUETYPE`) are represented as the fully qualified name of the type.
36
36
37
-
- Intrinsic types (for example, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREF. and ELEMENT_TYPE_VOID) are represented as the fully qualified name of the corresponding full type, for example, **System.Int32** or **System.TypedReference**.
37
+
- Intrinsic types (for example, `ELEMENT_TYPE_I4`, `ELEMENT_TYPE_OBJECT`, `ELEMENT_TYPE_STRING`, `ELEMENT_TYPE_TYPEDBYREF`, and `ELEMENT_TYPE_VOID`) are represented as the fully qualified name of the corresponding full type, for example, **`System.Int32`** or **`System.TypedReference`**.
38
38
39
-
- ELEMENT_TYPE_PTR is represented as a '*' following the modified type.
39
+
-`ELEMENT_TYPE_PTR` is represented as a '`*`' following the modified type.
40
40
41
-
- ELEMENT_TYPE_BYREF is represented as a '\@' following the modified type.
41
+
-`ELEMENT_TYPE_BYREF` is represented as a '`@`' following the modified type.
42
42
43
-
- ELEMENT_TYPE_PINNED is represented as a '^' following the modified type. The MSVC compiler never generates this.
43
+
-`ELEMENT_TYPE_PINNED` is represented as a '`^`' following the modified type. The MSVC compiler never generates this element.
44
44
45
-
- ELEMENT_TYPE_CMOD_REQ is represented as a '|' and the fully qualified name of the modifier class, following the modified type. The MSVC compiler never generates this.
45
+
-`ELEMENT_TYPE_CMOD_REQ` is represented as a '`|`' and the fully qualified name of the modifier class, following the modified type. The MSVC compiler never generates this element.
46
46
47
-
- ELEMENT_TYPE_CMOD_OPT is represented as a '!' and the fully qualified name of the modifier class, following the modified type.
47
+
-`ELEMENT_TYPE_CMOD_OPT` is represented as a '`!`' and the fully qualified name of the modifier class, following the modified type.
48
48
49
-
- ELEMENT_TYPE_SZARRAY is represented as "[]" following the element type of the array.
49
+
-`ELEMENT_TYPE_SZARRAY` is represented as "`[]`" following the element type of the array.
50
50
51
-
- ELEMENT_TYPE_GENERICARRAY is represented as "[?]" following the element type of the array. The MSVC compiler never generates this.
51
+
-`ELEMENT_TYPE_GENERICARRAY` is represented as "`[?]`" following the element type of the array. The MSVC compiler never generates this element.
52
52
53
-
- ELEMENT_TYPE_ARRAY is represented as [*lowerbound*:`size`,*lowerbound*:`size`] where the number of commas is the rank - 1, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it is simply omitted. If the lower bound and size for a particular dimension are omitted, the ':' is omitted as well. For example, a 2-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:].
53
+
-`ELEMENT_TYPE_ARRAY` is represented as `[`lower bound`:`size`,`lower bound`:`size`]` where the number of commas is the rank - 1, and the lower bound and size of each dimension, if known, are represented in decimal. If a lower bound or size isn't specified, it's omitted. If the lower bound and size are omitted for a particular dimension, the '`:`' is omitted as well. For example, a 2-dimensional array with 1 as the lower bound and unspecified sizes is represented as `[1:,1:]`.
54
54
55
-
- ELEMENT_TYPE_FNPTR is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The MSVC compiler never generates this.
55
+
-`ELEMENT_TYPE_FNPTR` is represented as "=FUNC:`type`(*signature*)", where `type` is the return type, and *signature* is the arguments of the method. If there are no arguments, the parentheses are omitted. The MSVC compiler never generates this element.
56
56
57
-
The following signature components are not represented because they are never used for differentiating overloaded methods:
57
+
The following signature components aren't represented because they're never used for differentiating overloaded methods:
58
58
59
-
-calling convention
59
+
-Calling convention
60
60
61
-
-return type
61
+
-Return type
62
62
63
-
- ELEMENT_TYPE_SENTINEL
63
+
-`ELEMENT_TYPE_SENTINEL`
64
64
65
-
- For conversion operators only, the return value of the method is encoded as a '~' followed by the return type, as previously encoded.
65
+
- For conversion operators only, the return value of the method is encoded as a '`~`' followed by the return type, as previously encoded.
66
66
67
67
- For generic types, the name of the type will be followed by a back tick and then a number that indicates the number of generic type parameters. For example,
68
68
69
69
```xml
70
70
<membername="T:MyClass`2">
71
71
```
72
72
73
-
For a type that is defined as `public class MyClass<T, U>`.
73
+
The example shows a type that's defined as `public class MyClass<T, U>`.
74
74
75
-
For methods taking generic types as parameters, the generic type parameters are specified as numbers prefaced with back ticks (for example \`0, \`1). Each number representing a zero-based array notation for the type's generic parameters.
75
+
For methods that take generic types as parameters, the generic type parameters are specified as numbers prefaced with back ticks (for example \`0, \`1). Each number represents a zero-based array position for the type's generic parameters.
Copy file name to clipboardExpand all lines: docs/build/reference/list-visual-cpp.md
+14-14Lines changed: 14 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
---
2
-
description: "Learn more about: <list> and <listheader>"
3
-
title: "<list> (C++ documentation comments)"
4
-
ms.date: "11/04/2016"
2
+
description: "Learn more about: <list> and <listheader>"
3
+
title: "<list> (C++ documentation comments)"
4
+
ms.date: 12/03/2021
5
5
f1_keywords: ["list"]
6
6
helpviewer_keywords: ["list C++ XML tag", "<list> C++ XML tag"]
7
7
ms.assetid: c792a10b-0451-422c-9aa0-604116e69d64
8
8
---
9
-
# <list> and <listheader>
9
+
# `<list>` and `<listheader>` documentation tags
10
10
11
-
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.
11
+
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.
12
12
13
13
## Syntax
14
14
@@ -25,21 +25,21 @@ The \<listheader> block is used to define the heading row of either a table or d
25
25
</list>
26
26
```
27
27
28
-
####Parameters
28
+
### Parameters
29
29
30
-
*term*<br/>
31
-
A term to define, which will be defined in `description`.
30
+
*`term`*\
31
+
A term to define, which will be defined in *`description`*.
32
32
33
-
*description*<br/>
34
-
Either an item in a bullet or numbered list or the definition of a `term`.
33
+
*`description`*\
34
+
Either an item in a bullet or numbered list or the definition of a *`term`*.
35
35
36
36
## Remarks
37
37
38
-
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`.
38
+
Each item in the list is specified with an `<item>` block. When creating a definition list, you'll 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`*.
39
39
40
-
A list or table can have as many \<item> blocks as needed.
40
+
A list or table can have as many `<item>` blocks as needed.
41
41
42
-
Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file.
42
+
Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file.
description: "Learn more about: XML documentation tag <para>"
3
+
title: "<para> documentation tag"
4
+
ms.date: 12/03/2021
5
5
f1_keywords: ["<para>"]
6
6
helpviewer_keywords: ["<para> C++ XML tag", "para C++ XML tag"]
7
7
ms.assetid: 35f2a1b3-bc14-4f13-bcb0-c39ccbf74d59
8
8
---
9
-
# <para>
9
+
# `<para>` documentation tag
10
10
11
-
The \<para> tag is for use inside a tag, such as [\<summary>](summary-visual-cpp.md), [\<remarks>](remarks-visual-cpp.md), or [\<returns>](returns-visual-cpp.md), and lets you add structure to the text.
11
+
The `<para>` tag is for use inside a tag, such as [`<summary>`](summary-visual-cpp.md), [`<remarks>`](remarks-visual-cpp.md), or [`<returns>`](returns-visual-cpp.md), and lets you add structure to the text.
12
12
13
13
## Syntax
14
14
15
-
```
16
-
<para>content</para>
15
+
```cpp
16
+
/// <para>content</para>
17
17
```
18
18
19
-
####Parameters
19
+
### Parameters
20
20
21
-
*content*<br/>
21
+
*`content`*\
22
22
The text of the paragraph.
23
23
24
24
## Remarks
25
25
26
-
Compile with [/doc](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file.
26
+
Compile with [`/doc`](doc-process-documentation-comments-c-cpp.md) to process documentation comments to a file.
27
27
28
28
## Example
29
29
30
-
See [\<summary>](summary-visual-cpp.md) for an example of using \<para>.
30
+
See [`<summary>`](summary-visual-cpp.md) for an example of using `<para>`.
0 commit comments