Recommend <remarks> rather than <remark>
Fixes https://github.com/dotnet/csharplang/issues/2435 and updates `<remark>` to `<remarks>`, per the original text in [ECMA-334](https://ecma-international.org/publications/files/ECMA-ST/ECMA-334.pdf) §D.3.12.
This commit is contained in:
parent
7f7fc6e9e1
commit
4da0c18183
|
@ -1,4 +1,4 @@
|
|||
# Documentation comments
|
||||
# Documentation comments
|
||||
|
||||
C# provides a mechanism for programmers to document their code using a special comment syntax that contains XML text. In source code files, comments having a certain form can be used to direct a tool to produce XML from those comments and the source code elements, which they precede. Comments using such syntax are called ***documentation comments***. They must immediately precede a user-defined type (such as a class, delegate, or interface) or a member (such as a field, event, property, or method). The XML generation tool is called the ***documentation generator***. (This generator could be, but need not be, the C# compiler itself.) The output produced by the documentation generator is called the ***documentation file***. A documentation file is used as input to a ***documentation viewer***; a tool intended to produce some sort of visual display of type information and its associated documentation.
|
||||
|
||||
|
@ -65,7 +65,7 @@ The documentation generator must accept and process any tag that is valid accord
|
|||
| `<param>` | [`<param>`](documentation-comments.md#param) | Describe a parameter for a method or constructor |
|
||||
| `<paramref>` | [`<paramref>`](documentation-comments.md#paramref) | Identify that a word is a parameter name |
|
||||
| `<permission>` | [`<permission>`](documentation-comments.md#permission) | Document the security accessibility of a member |
|
||||
| `<remark>` | [`<remark>`](documentation-comments.md#remark) | Describe additional information about a type |
|
||||
| `<remarks>` | [`<remarks>`](documentation-comments.md#remarks) | Describe additional information about a type |
|
||||
| `<returns>` | [`<returns>`](documentation-comments.md#returns) | Describe the return value of a method |
|
||||
| `<see>` | [`<see>`](documentation-comments.md#see) | Specify a link |
|
||||
| `<seealso>` | [`<seealso>`](documentation-comments.md#seealso) | Generate a See Also entry |
|
||||
|
@ -277,7 +277,7 @@ public class MyClass
|
|||
|
||||
### `<para>`
|
||||
|
||||
This tag is for use inside other tags, such as `<summary>` ([`<remark>`](documentation-comments.md#remark)) or `<returns>` ([`<returns>`](documentation-comments.md#returns)), and permits structure to be added to text.
|
||||
This tag is for use inside other tags, such as `<summary>` ([`<remarks>`](documentation-comments.md#remarks)) or `<returns>` ([`<returns>`](documentation-comments.md#returns)), and permits structure to be added to text.
|
||||
|
||||
__Syntax:__
|
||||
|
||||
|
@ -379,14 +379,14 @@ public static void Test() {
|
|||
}
|
||||
```
|
||||
|
||||
### `<remark>`
|
||||
### `<remarks>`
|
||||
|
||||
This tag is used to specify extra information about a type. (Use `<summary>` ([`<summary>`](documentation-comments.md#summary)) to describe the type itself and the members of a type.)
|
||||
|
||||
__Syntax:__
|
||||
|
||||
```xml
|
||||
<remark>description</remark>
|
||||
<remarks>description</remarks>
|
||||
```
|
||||
|
||||
where `description` is the text of the remark.
|
||||
|
@ -396,7 +396,7 @@ __Example:__
|
|||
```csharp
|
||||
/// <summary>Class <c>Point</c> models a point in a
|
||||
/// two-dimensional plane.</summary>
|
||||
/// <remark>Uses polar coordinates</remark>
|
||||
/// <remarks>Uses polar coordinates</remarks>
|
||||
public class Point
|
||||
{
|
||||
// ...
|
||||
|
@ -485,7 +485,7 @@ public override bool Equals(object o) {
|
|||
|
||||
### `<summary>`
|
||||
|
||||
This tag can be used to describe a type or a member of a type. Use `<remark>` ([`<remark>`](documentation-comments.md#remark)) to describe the type itself.
|
||||
This tag can be used to describe a type or a member of a type. Use `<remarks>` ([`<remarks>`](documentation-comments.md#remarks)) to describe the type itself.
|
||||
|
||||
__Syntax:__
|
||||
|
||||
|
@ -599,7 +599,7 @@ The documentation generator observes the following rules when it generates the I
|
|||
* Arguments are represented by their documentation name, which is based on their fully qualified name, modified as follows:
|
||||
* Arguments that represent generic types have an appended `` ` `` (backtick) character followed by the number of type parameters
|
||||
* Arguments having the `out` or `ref` modifier have an `@` following their type name. Arguments passed by value or via `params` have no special notation.
|
||||
* Arguments that are arrays are represented as `[lowerbound:size, ... , lowerbound:size]` where the number of commas is the rank less one, 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 omitted. If the lower bound and size for a particular dimension are omitted, the `:` is omitted as well. Jagged arrays are represented by one `[]` per level.
|
||||
* Arguments that are arrays are represented as `[lowerbound:size, ... , lowerbound:size]` where the number of commas is the rank less one, 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 omitted. If the lower bound and size for a particular dimension are omitted, the `:` is omitted as well. Jagged arrays are represented by one `[]` per level.
|
||||
* Arguments that have pointer types other than void are represented using a `*` following the type name. A void pointer is represented using a type name of `System.Void`.
|
||||
* Arguments that refer to generic type parameters defined on types are encoded using the `` ` `` (backtick) character followed by the zero-based index of the type parameter.
|
||||
* Arguments that use generic type parameters defined in methods use a double-backtick ``` `` ``` instead of the `` ` `` used for types.
|
||||
|
|
Loading…
Reference in a new issue