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:
Scott Dorman 2019-04-15 08:47:20 -04:00 committed by Neal Gafter
parent 7f7fc6e9e1
commit 4da0c18183

View file

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