Formatting of XML comments for ISymbol

src/Compilers/Core/Portable/Symbols/ISymbol.cs

@@ -38,12 +38,14 @@ public interface ISymbol : IEquatable<ISymbol>
         /// <summary>
         /// Gets the name of a symbol as it appears in metadata. Most of the time, this
         /// is the same as the Name property, with the following exceptions:
-        /// 1) The metadata name of generic types includes the "`1", "`2" etc. suffix that
+        /// <list type="number">
+        /// <item> The metadata name of generic types includes the "`1", "`2" etc. suffix that
         /// indicates the number of type parameters (it does not include, however, names of
-        /// containing types or namespaces).
-        /// 2) The metadata name of explicit interface names have spaces removed, compared to
-        /// the name property.
-        /// 3) The length of names is limited to not exceed metadata restrictions.
+        /// containing types or namespaces). </item>
+        /// <item> The metadata name of explicit interface names have spaces removed, compared to
+        /// the name property. </item>
+        /// <item> The length of names is limited to not exceed metadata restrictions. </item>
+        /// </list>
         /// </summary>
         string MetadataName { get; }
 
@@ -121,14 +123,18 @@ public interface ISymbol : IEquatable<ISymbol>
         /// used by code, but that are simply declared implicitly rather than with explicit language
         /// syntax.
         /// 
+        /// <para>
         /// Examples include (this list is not exhaustive):
-        ///   the default constructor for a class or struct that is created if one is not provided,
-        ///   the BeginInvoke/Invoke/EndInvoke methods for a delegate,
-        ///   the generated backing field for an auto property or a field-like event,
-        ///   the "this" parameter for non-static methods,
-        ///   the "value" parameter for a property setter,
-        ///   the parameters on indexer accessor methods (not on the indexer itself),
-        ///   methods in anonymous types
+        /// <list type="bullet">
+        /// <item> the default constructor for a class or struct that is created if one is not provided, </item>
+        /// <item> the BeginInvoke/Invoke/EndInvoke methods for a delegate, </item>
+        /// <item> the generated backing field for an auto property or a field-like event, </item>
+        /// <item> the "this" parameter for non-static methods, </item>
+        /// <item> the "value" parameter for a property setter, </item>
+        /// <item> the parameters on indexer accessor methods (not on the indexer itself), </item>
+        /// <item> methods in anonymous types </item>
+        /// </list>
+        /// </para>
         /// </remarks>
         bool IsImplicitlyDeclared { get; }
 
@@ -150,10 +156,12 @@ public interface ISymbol : IEquatable<ISymbol>
         /// one or more syntax nodes only if the symbol was declared in source code and also was
         /// not implicitly declared (see the IsImplicitlyDeclared property). 
         /// 
+        /// <para>
         /// Note that for namespace symbol, the declaring syntax might be declaring a nested namespace.
         /// For example, the declaring syntax node for N1 in "namespace N1.N2 {...}" is the entire
         /// NamespaceDeclarationSyntax for N1.N2. For the global namespace, the declaring syntax will
         /// be the CompilationUnitSyntax.
+        /// </para>
         /// </summary>
         /// <returns>
         /// The syntax node(s) that declared the symbol. If the symbol was declared in metadata
@@ -247,21 +255,31 @@ ImmutableArray<SymbolDisplayPart> ToMinimalDisplayParts(
         /// <summary>
         /// Indicates that this symbol uses metadata that cannot be supported by the language.
         /// 
+        /// <para>
         /// Examples include:
-        ///    - Pointer types in VB
-        ///    - ByRef return type
-        ///    - Required custom modifiers
-        ///    
+        /// <list type="bullet">
+        /// <item> Pointer types in VB </item>
+        /// <item> ByRef return type </item>
+        /// <item> Required custom modifiers </item>
+        /// </list>
+        /// </para>
+        /// 
+        /// <para>
         /// This is distinguished from, for example, references to metadata symbols defined in assemblies that weren't referenced.
         /// Symbols where this returns true can never be used successfully, and thus should never appear in any IDE feature.
+        /// </para>
         /// 
+        /// <para>
         /// This is set for metadata symbols, as follows:
-        /// Type - if a type is unsupported (e.g., a pointer type, etc.)
-        /// Method - parameter or return type is unsupported
-        /// Field - type is unsupported
-        /// Event - type is unsupported
-        /// Property - type is unsupported
-        /// Parameter - type is unsupported
+        /// <list type="bullet">
+        /// <item> Type - if a type is unsupported (e.g., a pointer type, etc.) </item>
+        /// <item> Method - parameter or return type is unsupported </item>
+        /// <item> Field - type is unsupported </item>
+        /// <item> Event - type is unsupported </item>
+        /// <item> Property - type is unsupported </item>
+        /// <item> Parameter - type is unsupported </item>
+        /// </list>
+        /// </para>
         /// </summary>
         bool HasUnsupportedMetadata { get; }
     }