Starting using DocumentationAnalyzers

eng/Versions.props

@@ -30,6 +30,7 @@
     <IdentityServer4EntityFrameworkVersion>3.0.0</IdentityServer4EntityFrameworkVersion>
     <FxCopAnalyzersVersion>3.0.0</FxCopAnalyzersVersion>
     <StyleCopAnalyzersVersion>1.1.118</StyleCopAnalyzersVersion>
+    <DotNetAnalyzersDocumentationAnalyzersVersion>1.0.0-beta.59</DotNetAnalyzersDocumentationAnalyzersVersion>
     <BenchmarkDotNetVersion>0.12.0</BenchmarkDotNetVersion>
     <MicrosoftDataSqlClientVersion>2.0.0-preview3.20122.2</MicrosoftDataSqlClientVersion>
     <MicrosoftCSharpVersion>4.7.0</MicrosoftCSharpVersion>

rulesets/Documentation.ruleset

@@ -0,0 +1,21 @@
+<?xml version="1.0"?>
+<RuleSet Name="DocumentationAnalyzers" Description="DocumentationAnalyzers" ToolsVersion="15.0">
+  <Rules AnalyzerId="DocumentationAnalyzers" RuleNamespace="DocumentationAnalyzers">
+    <Rule Id="DOC100" Action="None" />    <!-- PlaceTextInParagraphs -->
+    <Rule Id="DOC101" Action="Warning" /> <!-- UseChildBlocksConsistently -->
+    <Rule Id="DOC102" Action="None" />    <!-- UseChildBlocksConsistentlyAcrossElementsOfTheSameKind -->
+    <Rule Id="DOC103" Action="Warning" /> <!-- UseUnicodeCharacters -->
+    <Rule Id="DOC104" Action="Warning" /> <!-- UseSeeLangword -->
+    <Rule Id="DOC105" Action="Warning" /> <!-- UseParamref -->
+    <Rule Id="DOC106" Action="Warning" /> <!-- UseTypeparamref -->
+    <Rule Id="DOC107" Action="Warning" /> <!-- UseSeeCref -->
+    <Rule Id="DOC108" Action="Warning" /> <!-- AvoidEmptyParagraphs -->
+    <Rule Id="DOC200" Action="Warning" /> <!-- UseXmlDocumentationSyntax -->
+    <Rule Id="DOC201" Action="Warning" /> <!-- ItemShouldHaveDescription -->
+    <Rule Id="DOC202" Action="Warning" /> <!-- UseSectionElementsCorrectly -->
+    <Rule Id="DOC203" Action="Warning" /> <!-- UseBlockElementsCorrectly -->
+    <Rule Id="DOC204" Action="Warning" /> <!-- UseInlineElementsCorrectly -->
+    <Rule Id="DOC207" Action="Warning" /> <!-- UseSeeLangwordCorrectly -->
+    <Rule Id="DOC209" Action="Warning" /> <!-- UseSeeHrefCorrectly -->
+  </Rules>
+</RuleSet>

rulesets/EFCore.ruleset

@@ -2,4 +2,5 @@
 <RuleSet Name="EFCore" ToolsVersion="15.0">
   <Include Path="StyleCop.ruleset" Action="Default" />
   <Include Path="FxCop.ruleset" Action="Default" />
+  <Include Path="Documentation.ruleset" Action="Default" />
 </RuleSet>

src/Directory.Build.props

@@ -9,6 +9,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.FxCopAnalyzers" Version="$(FxCopAnalyzersVersion)" PrivateAssets="All" />
+    <PackageReference Include="DotNetAnalyzers.DocumentationAnalyzers" Version="$(DotNetAnalyzersDocumentationAnalyzersVersion)" PrivateAssets="All" />
   </ItemGroup>
 
 </Project>

src/EFCore.Relational/Extensions/RelationalDatabaseFacadeExtensions.cs

@@ -127,9 +127,7 @@ public static Task MigrateAsync(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
         ///     <para>
         ///         However, <b>never</b> pass a concatenated or interpolated string (<c>$""</c>) with non-validated user-provided values
         ///         into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax,
@@ -165,9 +163,7 @@ public static int ExecuteSqlRaw(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
         /// </summary>
         /// <param name="databaseFacade"> The <see cref="DatabaseFacade" /> for the context. </param>
         /// <param name="sql"> The interpolated string representing a SQL query with parameters. </param>
@@ -196,9 +192,7 @@ public static int ExecuteSqlInterpolated(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
         ///     <para>
         ///         However, <b>never</b> pass a concatenated or interpolated string (<c>$""</c>) with non-validated user-provided values
         ///         into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax,
@@ -258,9 +252,7 @@ public static int ExecuteSqlRaw(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlInterpolatedAsync($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlInterpolatedAsync($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
         /// </summary>
         /// <param name="databaseFacade"> The <see cref="DatabaseFacade" /> for the context. </param>
         /// <param name="sql"> The interpolated string representing a SQL query with parameters. </param>
@@ -324,9 +316,7 @@ public static Task<int> ExecuteSqlRawAsync(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
         ///     <para>
         ///         However, <b>never</b> pass a concatenated or interpolated string (<c>$""</c>) with non-validated user-provided values
         ///         into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax,
@@ -364,9 +354,7 @@ public static Task<int> ExecuteSqlRawAsync(
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
-        ///     </para>
+        ///     <code>context.Database.ExecuteSqlRawAsync("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
         ///     <para>
         ///         However, <b>never</b> pass a concatenated or interpolated string (<c>$""</c>) with non-validated user-provided values
         ///         into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax,

src/EFCore.Relational/Extensions/RelationalQueryableExtensions.cs

@@ -66,9 +66,7 @@ public static DbCommand CreateDbCommand([NotNull] this IQueryable source)
         ///         attack. You can include parameter place holders in the SQL query string and then supply parameter values as additional
         ///         arguments. Any parameter values you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
-        ///     </para>
+        ///     <code>context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({0})", userSuppliedSearchTerm)</code>
         ///     <para>
         ///         However, <b>never</b> pass a concatenated or interpolated string (<c>$""</c>) with non-validated user-provided values
         ///         into this method. Doing so may expose your application to SQL injection attacks. To use the interpolated string syntax,
@@ -78,9 +76,7 @@ public static DbCommand CreateDbCommand([NotNull] this IQueryable source)
         ///         This overload also accepts DbParameter instances as parameter values. This allows you to use named
         ///         parameters in the SQL query string:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({@searchTerm})", new SqlParameter("@searchTerm", userSuppliedSearchTerm))</code>
-        ///     </para>
+        ///     <code>context.Blogs.FromSqlRaw("SELECT * FROM [dbo].[SearchBlogs]({@searchTerm})", new SqlParameter("@searchTerm", userSuppliedSearchTerm))</code>
         /// </summary>
         /// <typeparam name="TEntity"> The type of the elements of <paramref name="source" />. </typeparam>
         /// <param name="source">
@@ -114,16 +110,15 @@ public static IQueryable<TEntity> FromSqlRaw<TEntity>(
         ///     </para>
         ///     <para>
         ///         If the database provider supports composing on the supplied SQL, you can compose on top of the raw SQL query using
-        ///         LINQ operators - <code>context.Blogs.FromSqlInterpolated($"SELECT * FROM dbo.Blogs").OrderBy(b => b.Name)</code>.
+        ///         LINQ operators:
         ///     </para>
+        ///     <code>context.Blogs.FromSqlInterpolated($"SELECT * FROM dbo.Blogs").OrderBy(b => b.Name)</code>
         ///     <para>
         ///         As with any API that accepts SQL it is important to parameterize any user input to protect against a SQL injection
         ///         attack. You can include interpolated parameter place holders in the SQL query string. Any interpolated parameter values
         ///         you supply will automatically be converted to a DbParameter:
         ///     </para>
-        ///     <para>
-        ///         <code>context.Blogs.FromSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
-        ///     </para>
+        ///     <code>context.Blogs.FromSqlInterpolated($"SELECT * FROM [dbo].[SearchBlogs]({userSuppliedSearchTerm})")</code>
         /// </summary>
         /// <typeparam name="TEntity"> The type of the elements of <paramref name="source" />. </typeparam>
         /// <param name="source">

src/EFCore/Diagnostics/InterceptionResult`.cs

@@ -47,8 +47,8 @@ private InterceptionResult(TResult result)
         ///         The property can only be accessed if <see cref="HasResult" /> is true. The concept here
         ///         is the same as <see cref="Nullable{T}.Value" /> and <see cref="Nullable{T}.HasValue" />
         ///     </para>
-        ///     <exception cref="InvalidOperationException"> when <see cref="Result" /> is <see langword="false"/>.</exception>
         /// </summary>
+        /// <exception cref="InvalidOperationException"> when <see cref="Result" /> is <see langword="false"/>.</exception>
         public TResult Result
         {
             get

src/EFCore/Diagnostics/WarningsConfiguration.cs

@@ -134,9 +134,10 @@ public virtual WarningsConfiguration WithExplicit(
                 : null;
 
         /// <summary>
-        ///     Gets the <see cref="LogLevel" /> set for the given event ID, or <code>null</code>
+        ///     Gets the <see cref="LogLevel" /> set for the given event ID, or <see langword="null"/>
         ///     if no explicit behavior has been set.
         /// </summary>
+        /// <returns> The <see cref="LogLevel" /> set for the given event ID. </returns>
         public virtual LogLevel? GetLevel(EventId eventId)
             => _explicitBehaviors.TryGetValue(eventId.Id, out var warningBehavior)
                 ? warningBehavior.Level

src/EFCore/EF.cs

@@ -25,7 +25,9 @@ internal static readonly MethodInfo PropertyMethod
         ///     property in other scenarios.
         /// </summary>
         /// <example>
-        ///     The following code performs a filter using the a LastUpdated shadow state property.
+        ///     <para>
+        ///         The following code performs a filter using the a LastUpdated shadow state property.
+        ///     </para>
         ///     <code>
         /// var blogs = context.Blogs
         ///     .Where(b =&gt; EF.Property&lt;DateTime&gt;(b, "LastUpdated") > DateTime.Now.AddDays(-5));