Explain /// comments without elements (#44968)

* Explain `///` comments without elements

Fixes #44161

Yes, roslyn interprets these comments and exports them to the XML file. However, the text isn't in a child XML element, and won't be interpreted by other tools.

* build warning

Author: BillWagner

docs/csharp/language-reference/xmldoc/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Documentation comments - document APIs using /// comments"
 description: Learn about documentation comments. You can create documentation for your code by including XML elements in special comment fields. You can use other tools to build documentation layouts from comments.
-ms.date: 06/14/2023
+ms.date: 02/19/2025
 f1_keywords:
   - "cs.xml"
 helpviewer_keywords:
@@ -11,12 +11,11 @@ helpviewer_keywords:
   - "C# source code files"
   - "C# language, XML code comments"
   - "XML documentation comments [C#]"
-ms.assetid: 803b7f7b-7428-4725-b5db-9a6cff273199
 ---
 
 # Documentation comments
 
-C# source files can have structured comments that produce API documentation for the types defined in those files. The C# compiler produces an *XML* file that contains structured data representing the comments and the API signatures. Other tools can process that XML output to create human-readable documentation in the form of web pages or PDF files, for example.
+C# source files can include structured comments that produce API documentation for the types defined in those files. The C# compiler produces an *XML* file that contains structured data representing the comments and the API signatures. Other tools can process that XML output to create human-readable documentation in the form of web pages or PDF files, for example.
 
 This process provides many advantages for you to add API documentation in your code:
 
@@ -26,7 +25,7 @@ This process provides many advantages for you to add API documentation in your c
 
 Tools like Visual Studio provide IntelliSense for many common XML elements used in documentation comments.
 
-This article covers these topics:
+This article covers these articles:
 
 - Documentation comments and XML file generation
 - Tags validated by the C# compiler and Visual Studio
@@ -49,14 +48,14 @@ You set either the [**GenerateDocumentationFile**](../../../core/project-sdk/msb
 
 The use of XML doc comments requires delimiters that indicate where a documentation comment begins and ends. You use the following delimiters with the XML documentation tags:
 
-- `///` Single-line delimiter: The documentation examples and C# project templates use this form. If there's white space following the delimiter, it isn't included in the XML output.
+- `///` Single-line delimiter: The documentation examples and C# project templates use this form. If white space follows the delimiter, it isn't included in the XML output.
   > [!NOTE]
   > Visual Studio automatically inserts the `<summary>` and `</summary>` tags and positions your cursor within these tags after you type the `///` delimiter in the code editor. You can turn this feature on or off in the [Options dialog box](/visualstudio/ide/reference/options-text-editor-csharp-advanced).
 - `/** */` Multiline delimiters: The `/** */` delimiters have the following formatting rules:
   - On the line that contains the `/**` delimiter, if the rest of the line is white space, the line isn't processed for comments. If the first character after the `/**` delimiter 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.
   - On the line that contains the `*/` delimiter, if there's 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.
   - For the lines after the one that begins with the `/**` delimiter, the compiler looks for a common pattern at the beginning of each line. The pattern can consist of optional white space and/or an asterisk (`*`), followed by more optional white space. If the compiler finds a common pattern at the beginning of each line that doesn't begin with the `/**` delimiter or end with the `*/` delimiter, it ignores that pattern for each line.
-  - The only part of the following comment that's processed is the line that begins with `<summary>`. The three tag formats produce the same comments.
+  - The only part of the following comment processed is the line that begins with `<summary>`. The three tag formats produce the same comments.
 
     ```csharp
     /** <summary>text</summary> */
@@ -100,10 +99,10 @@ The use of XML doc comments requires delimiters that indicate where a documentat
     ```
     <!-- markdownlint-enable MD010 -->
 
-To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (`&lt;` and `&gt;`).  To refer to generic identifiers in code reference (`cref`) elements, you can use either the escape characters (for example, `cref="List&lt;T&gt;"`) or braces (`cref="List{T}"`).  As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to the author when referring to generic identifiers.
+To refer to XML elements (for example, your function processes specific XML elements that you want to describe in an XML documentation comment), you can use the standard quoting mechanism (`&lt;` and `&gt;`). To refer to generic identifiers in code reference (`cref`) elements, you can use either the escape characters (for example, `cref="List&lt;T&gt;"`) or braces (`cref="List{T}"`). As a special case, the compiler parses the braces as angle brackets to make the documentation comment less cumbersome to the author when referring to generic identifiers.
 
 > [!NOTE]
-> The XML documentation comments are not metadata; they are not included in the compiled assembly and therefore they are not accessible through reflection.
+> If you write comments using the single line XML comment delimiter, `///`, but don't include any tags, the compiler adds the text of those comments to the XML output file. However, the output doesn't include XML elements such as `<summary>`. Most tools that consume XML comments (including Visual Studio intellisense) don't read these comments.
 
 ## Tools that accept XML documentation input
 
@@ -113,6 +112,9 @@ The following tools create output from XML comments:
 - [Sandcastle](https://github.com/EWSoftware/SHFB): The *Sandcastle tools* create help files for managed class libraries containing both conceptual and API reference pages. The Sandcastle tools are command-line based and have no GUI front-end, project management features, or automated build process. The Sandcastle Help File Builder provides standalone GUI and command-line-based tools to build a help file in an automated fashion. A Visual Studio integration package is also available for it so that help projects can be created and managed entirely from within Visual Studio.
 - [Doxygen](https://github.com/doxygen/doxygen): *Doxygen* generates an online documentation browser (in HTML) or an offline reference manual (in LaTeX) from a set of documented source files. There's also support for generating output in RTF (MS Word), PostScript, hyperlinked PDF, compressed HTML, DocBook, and Unix manual pages. You can configure Doxygen to extract the code structure from undocumented source files.
 
+> [!NOTE]
+> The XML documentation comments aren't metadata; they aren't included in the compiled assembly and therefore they aren't accessible through reflection.
+
 ### ID strings
 
 Each type or member is stored in an element in the output XML file. Each of those elements has a unique ID string that identifies the type or member. The ID string must account for operators, parameters, return values, generic type parameters, `ref`, `in`, and `out` parameters. To encode all those potential elements, the compiler follows clearly defined rules for generating the ID strings. Programs that process the XML file use the ID string to identify the corresponding .NET metadata or reflection item that the documentation applies to.
@@ -132,15 +134,15 @@ The compiler observes the following rules when it generates the ID strings:
   | `E` | event |  |
   | `!` | error string | The rest of the string provides information about the error. The C# compiler generates error information for links that can't be resolved. |
 
-- 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(s), and namespace are separated by periods. If the name of the item itself has periods, they're replaced with 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 is "System.String.#ctor".
+- 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(s), and namespace are separated by periods. If the name of the item itself has periods, they're replaced with the hash-sign ('#'). The grammar assumes that no item has a hash-sign directly in its name. For example, the fully qualified name of the String constructor is "System.String.#ctor".
 - For properties and methods, the parameter list enclosed in parentheses follows. If there are no parameters, no parentheses are present. The parameters are separated by commas. The encoding of each parameter follows directly how it's encoded in a .NET signature (See <xref:Microsoft.VisualStudio.CorDebugInterop.CorElementType?displayProperty=fullName> for definitions of the all caps elements in the following list):
   - Base types. Regular types (`ELEMENT_TYPE_CLASS` or `ELEMENT_TYPE_VALUETYPE`) are represented as the fully qualified name of the type.
   - 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`.
   - `ELEMENT_TYPE_PTR` is represented as a '\*' following the modified type.
   - `ELEMENT_TYPE_BYREF` is represented as a '\@' following the modified type.
   - `ELEMENT_TYPE_CMOD_OPT` is represented as a '!' and the fully qualified name of the modifier class, following the modified type.
   - `ELEMENT_TYPE_SZARRAY` is represented as "[]" following the element type of the array.
-  - `ELEMENT_TYPE_ARRAY` is represented as [*lower bound*:`size`,*lower bound*:`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 isn't specified, it's omitted. If the lower bound and size for a particular dimension is omitted, the ':' is omitted as well. For example, a two-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:].
+  - `ELEMENT_TYPE_ARRAY` is represented as [*lower bound*:`size`,*lower bound*:`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. The lower bound and size are omitted if they aren't specified. If the lower bound and size for a particular dimension is omitted, the ':' is omitted as well. For example, a two-dimensional array with 1 as the lower bounds and unspecified sizes is [1:,1:].
 - For conversion operators only (`op_Implicit` and `op_Explicit`), the return value of the method is encoded as a `~` followed by the return type. For example:
      `<member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32">` is the tag for the cast operator `public static explicit operator int (decimal value);` declared in the `System.Decimal` class.
 - For generic types, the name of the type is followed by a backtick and then a number that indicates the number of generic type parameters. For example: