From 497db9b94df0b4660086f8329cf6396aa425c022 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 22 Nov 2023 11:43:46 -0500 Subject: [PATCH 1/5] Correct ID string for generic elements Fixes #771 Add instances where the `<` and `>` characters are replaced by `{` and `}` in the string IDs. --- standard/documentation-comments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index cbfd7634c..e7a2f6f33 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -691,7 +691,7 @@ The documentation generator observes the following rules when it generates the I T | Type (such as class, delegate, enum, interface, and struct) ! | Error string; the rest of the string provides information about the error. For example, the documentation generator generates error information for links that cannot be resolved. -- The second part of the string is the fully qualified name of the element, starting at the root of the namespace. The name of the element, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they are replaced by \# (U+0023) characters. (It is assumed that no element has this character in its name.) +- The second part of the string is the fully qualified name of the element, starting at the root of the namespace. The name of the element, its enclosing type(s), and namespace are separated by periods. If the name of the item itself has periods, they are replaced by \# (U+0023) characters. (It is assumed that no element has this character in its name.) Type arguments in the fully qualified name, for when a member explicitly implements a member of a generic interface, are encoded by replacing the "`<`" and "`>`" surrounding them with the "`{`" and "`}`" characters. - For methods and properties with arguments, the argument list follows, enclosed in parentheses. For those without arguments, the parentheses are omitted. The arguments are separated by commas. The encoding of each argument is the same as a CLI signature, as follows: - 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 “`'`” character followed by the number of type parameters @@ -976,7 +976,7 @@ IDs: The complete set of binary operator function names used is as follows: `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`, and `op_GreaterThanOrEqual`. -**Conversion operators** have a trailing “`~`” followed by the return type. +**Conversion operators** have a trailing “`~`” followed by the return type. When either the source or destination of a conversion operator is a generic type, the "`<`" and "`">`" characters are replaced by the "`{`" and "`}`" characters, respectively. ```csharp From 633c4b2296500565727ede11498b7984fde7cbe4 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 22 Nov 2023 11:55:54 -0500 Subject: [PATCH 2/5] Fix array encoding Fixes #772 Single dimension arrays are encoded as "[]" rather than "[0]". --- standard/documentation-comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index e7a2f6f33..41ab6568b 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -696,7 +696,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 “`'`” character followed by the number of type parameters - Arguments having the `in`, `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 multi-dimensional 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. Single dimension arrays omit the lower bound when the lower bound is 0 (the default) (§17.1). - 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 “`` ` ``” 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. From b16aef797c3759e6362686d0aa83a7badd4187f8 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 22 Nov 2023 12:02:14 -0500 Subject: [PATCH 3/5] Add name attribute to param tags Fixes #915 In the example in D5, add the "name=" attribute on all param tags. --- standard/documentation-comments.md | 44 +++++++++++++++--------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index 41ab6568b..b6472f7b1 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -1031,8 +1031,8 @@ namespace Graphics /// This constructor initializes the new Point to /// (,). /// - /// xPosition is the new Point's x-coordinate. - /// yPosition is the new Point's y-coordinate. + /// xPosition is the new Point's x-coordinate. + /// yPosition is the new Point's y-coordinate. public Point(int xPosition, int yPosition) { X = xPosition; @@ -1043,8 +1043,8 @@ namespace Graphics /// This method changes the point's location to /// the given coordinates. /// - /// xPosition is the new x-coordinate. - /// yPosition is the new y-coordinate. + /// xPosition is the new x-coordinate. + /// yPosition is the new y-coordinate. public void Move(int xPosition, int yPosition) { X = xPosition; @@ -1063,8 +1063,8 @@ namespace Graphics /// /// /// - /// dx is the relative x-offset. - /// dy is the relative y-offset. + /// dx is the relative x-offset. + /// dy is the relative y-offset. public void Translate(int dx, int dy) { X += dx; @@ -1074,7 +1074,7 @@ namespace Graphics /// /// This method determines whether two Points have the same location. /// - /// + /// /// o is the object to be compared to the current object. /// /// @@ -1122,8 +1122,8 @@ namespace Graphics /// /// This operator determines whether two Points have the same location. /// - /// p1 is the first Point to be compared. - /// p2 is the second Point to be compared. + /// p1 is the first Point to be compared. + /// p2 is the second Point to be compared. /// /// True if the Points have the same location and they have /// the exact same type; otherwise, false. @@ -1146,8 +1146,8 @@ namespace Graphics /// /// This operator determines whether two Points have the same location. /// - /// p1 is the first Point to be compared. - /// p2 is the second Point to be compared. + /// p1 is the first Point to be compared. + /// p2 is the second Point to be compared. /// /// True if the Points do not have the same location and the /// exact same type; otherwise, false. @@ -1183,8 +1183,8 @@ Here is the output produced by one documentation generator when given the source This constructor initializes the new Point to (,). - xPosition is the new Point's x-coordinate. - yPosition is the new Point's y-coordinate. + xPosition is the new Point's x-coordinate. + yPosition is the new Point's y-coordinate. @@ -1192,8 +1192,8 @@ Here is the output produced by one documentation generator when given the source the given coordinates. - xPosition is the new x-coordinate. - yPosition is the new y-coordinate. + xPosition is the new x-coordinate. + yPosition is the new y-coordinate. @@ -1208,14 +1208,14 @@ Here is the output produced by one documentation generator when given the source - dx is the relative x-offset. - dy is the relative y-offset. + dx is the relative x-offset. + dy is the relative y-offset. This method determines whether two Points have the same location. - + o is the object to be compared to the current object. @@ -1240,8 +1240,8 @@ Here is the output produced by one documentation generator when given the source This operator determines whether two Points have the same location. - p1 is the first Point to be compared. - p2 is the second Point to be compared. + p1 is the first Point to be compared. + p2 is the second Point to be compared. True if the Points have the same location and they have the exact same type; otherwise, false. @@ -1255,8 +1255,8 @@ Here is the output produced by one documentation generator when given the source This operator determines whether two Points have the same location. - p1 is the first Point to be compared. - p2 is the second Point to be compared. + p1 is the first Point to be compared. + p2 is the second Point to be compared. True if the Points do not have the same location and the exact same type; otherwise, false. From f0281aaf160be1fba5c03c33a717b81529e31561 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Wed, 22 Nov 2023 13:29:57 -0500 Subject: [PATCH 4/5] Address nit I thought about removing the `` tags in my previous commit, but I was waiting for other opinions, and wanted to verify that there was at least one tag like that still in the example. --- standard/documentation-comments.md | 44 +++++++++++++++--------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index b6472f7b1..1bb3e5e17 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -1031,8 +1031,8 @@ namespace Graphics /// This constructor initializes the new Point to /// (,). /// - /// xPosition is the new Point's x-coordinate. - /// yPosition is the new Point's y-coordinate. + /// The new Point's x-coordinate. + /// The new Point's y-coordinate. public Point(int xPosition, int yPosition) { X = xPosition; @@ -1043,8 +1043,8 @@ namespace Graphics /// This method changes the point's location to /// the given coordinates. /// - /// xPosition is the new x-coordinate. - /// yPosition is the new y-coordinate. + /// The new x-coordinate. + /// The new y-coordinate. public void Move(int xPosition, int yPosition) { X = xPosition; @@ -1063,8 +1063,8 @@ namespace Graphics /// /// /// - /// dx is the relative x-offset. - /// dy is the relative y-offset. + /// The relative x-offset. + /// The relative y-offset. public void Translate(int dx, int dy) { X += dx; @@ -1075,7 +1075,7 @@ namespace Graphics /// This method determines whether two Points have the same location. /// /// - /// o is the object to be compared to the current object. + /// The object to be compared to the current object. /// /// /// True if the Points have the same location and they have @@ -1122,8 +1122,8 @@ namespace Graphics /// /// This operator determines whether two Points have the same location. /// - /// p1 is the first Point to be compared. - /// p2 is the second Point to be compared. + /// The first Point to be compared. + /// The second Point to be compared. /// /// True if the Points have the same location and they have /// the exact same type; otherwise, false. @@ -1146,8 +1146,8 @@ namespace Graphics /// /// This operator determines whether two Points have the same location. /// - /// p1 is the first Point to be compared. - /// p2 is the second Point to be compared. + /// The first Point to be compared. + /// The second Point to be compared. /// /// True if the Points do not have the same location and the /// exact same type; otherwise, false. @@ -1183,8 +1183,8 @@ Here is the output produced by one documentation generator when given the source This constructor initializes the new Point to (,). - xPosition is the new Point's x-coordinate. - yPosition is the new Point's y-coordinate. + The new Point's x-coordinate. + The new Point's y-coordinate. @@ -1192,8 +1192,8 @@ Here is the output produced by one documentation generator when given the source the given coordinates. - xPosition is the new x-coordinate. - yPosition is the new y-coordinate. + The new x-coordinate. + The new y-coordinate. @@ -1208,15 +1208,15 @@ Here is the output produced by one documentation generator when given the source - dx is the relative x-offset. - dy is the relative y-offset. + The relative x-offset. + The relative y-offset. This method determines whether two Points have the same location. - o is the object to be compared to the current object. + The object to be compared to the current object. True if the Points have the same location and they have @@ -1240,8 +1240,8 @@ Here is the output produced by one documentation generator when given the source This operator determines whether two Points have the same location. - p1 is the first Point to be compared. - p2 is the second Point to be compared. + The first Point to be compared. + The second Point to be compared. True if the Points have the same location and they have the exact same type; otherwise, false. @@ -1255,8 +1255,8 @@ Here is the output produced by one documentation generator when given the source This operator determines whether two Points have the same location. - p1 is the first Point to be compared. - p2 is the second Point to be compared. + The first Point to be compared. + The second Point to be compared. True if the Points do not have the same location and the exact same type; otherwise, false. From d9a81d287343963e245b77dbedd0dda417da0390 Mon Sep 17 00:00:00 2001 From: Neal Gafter Date: Wed, 29 Nov 2023 13:15:27 -0800 Subject: [PATCH 5/5] Update standard/documentation-comments.md Co-authored-by: Jon Skeet --- standard/documentation-comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/standard/documentation-comments.md b/standard/documentation-comments.md index 1bb3e5e17..c8a73d70d 100644 --- a/standard/documentation-comments.md +++ b/standard/documentation-comments.md @@ -696,7 +696,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 “`'`” character followed by the number of type parameters - Arguments having the `in`, `out` or `ref` modifier have an `@` following their type name. Arguments passed by value or via `params` have no special notation. - - Arguments that are multi-dimensional 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. Single dimension arrays omit the lower bound when the lower bound is 0 (the default) (§17.1). + - 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. Single dimensional arrays omit the lower bound when the lower bound is 0 (the default) (§17.1). - 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 “`` ` ``” 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.