Merge pull request fluentassertions#1303 from jnyrup/xmlSummaries

Make xml references syntactically correct

.editorconfig

@@ -55,8 +55,8 @@ csharp_style_var_when_type_is_apparent = false:none
 csharp_style_var_elsewhere = false:suggestion
 
 # use language keywords instead of BCL types
-dotnet_style_predefined_type_for_locals_parameters_members = true:suggestion
-dotnet_style_predefined_type_for_member_access = true:suggestion
+dotnet_style_predefined_type_for_locals_parameters_members = true:error
+dotnet_style_predefined_type_for_member_access = true:error
 
 # name all constant fields using PascalCase
 dotnet_naming_rule.constant_fields_should_be_pascal_case.severity = suggestion
@@ -90,14 +90,17 @@ csharp_style_expression_bodied_indexers = true:none
 csharp_style_expression_bodied_accessors = true:none
 
 # Pattern matching
-csharp_style_pattern_matching_over_is_with_cast_check = true:suggestion
-csharp_style_pattern_matching_over_as_with_null_check = true:suggestion
-csharp_style_inlined_variable_declaration = true:suggestion
+csharp_style_pattern_matching_over_is_with_cast_check = true:error
+csharp_style_pattern_matching_over_as_with_null_check = true:error
+csharp_style_inlined_variable_declaration = true:error
 
 # Null checking preferences
 csharp_style_throw_expression = true:suggestion
 csharp_style_conditional_delegate_call = true:suggestion
 
+dotnet_style_require_accessibility_modifiers = for_non_interface_members:error
+dotnet_style_readonly_field = true:error
+
 # Space preferences
 csharp_space_after_cast = false
 csharp_space_after_colon_in_inheritance_clause = true
@@ -131,6 +134,26 @@ dotnet_diagnostic.CA1305.severity = none
 dotnet_diagnostic.CA1307.severity = error
 dotnet_diagnostic.CA1308.severity = error
 dotnet_diagnostic.CA1309.severity = error
+dotnet_diagnostic.CA3075.severity = none
+dotnet_diagnostic.CA5369.severity = none
 
 # Banned API Analyzers
 dotnet_diagnostic.RS0030.severity = error
+
+# IDE0004: Remove unnecessary cast
+dotnet_diagnostic.IDE0004.severity = error
+
+# IDE0005: Remove unnecessary usings/imports
+dotnet_diagnostic.IDE0005.severity = error
+
+# IDE0051: Remove unused private members (no reads or writes)
+dotnet_diagnostic.IDE0051.severity = error
+
+# IDE0052: Remove unread private members (writes but no reads)
+dotnet_diagnostic.IDE0052.severity = error
+
+# IDE0055: Fix formatting
+dotnet_diagnostic.IDE0055.severity = suggestion
+
+# CS1574: XML comment on 'construct' has syntactically incorrect cref attribute 'name'
+dotnet_diagnostic.CS1574.severity = error

Build/.editorconfig

@@ -8,3 +8,6 @@ dotnet_style_require_accessibility_modifiers = never:warning
 csharp_style_expression_bodied_properties = true:warning
 csharp_style_expression_bodied_indexers = true:warning
 csharp_style_expression_bodied_accessors = true:warning
+
+dotnet_diagnostic.IDE0044.severity = none
+dotnet_diagnostic.IDE0051.severity = none

Build/Build.cs

@@ -16,11 +16,13 @@
 [DotNetVerbosityMapping]
 class Build : NukeBuild
 {
-    /// Support plugins are available for:
-    ///   - JetBrains ReSharper        https://nuke.build/resharper
-    ///   - JetBrains Rider            https://nuke.build/rider
-    ///   - Microsoft VisualStudio     https://nuke.build/visualstudio
-    ///   - Microsoft VSCode           https://nuke.build/vscode
+    /* Support plugins are available for:
+       - JetBrains ReSharper        https://nuke.build/resharper
+       - JetBrains Rider            https://nuke.build/rider
+       - Microsoft VisualStudio     https://nuke.build/visualstudio
+       - Microsoft VSCode           https://nuke.build/vscode
+    */
+
     public static int Main() => Execute<Build>(
         x => x.UnitTests,
         x => x.Pack);

Src/FluentAssertions/AndConstraint.cs

@@ -8,7 +8,7 @@ public class AndConstraint<T>
         public T And { get; }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="System.Object"/> class.
+        /// Initializes a new instance of the <see cref="AndConstraint{T}"/> class.
         /// </summary>
         public AndConstraint(T parentConstraint)
         {

Src/FluentAssertions/AssertionExtensions.cs

@@ -8,7 +8,9 @@
 using System.Xml.Linq;
 using FluentAssertions.Collections;
 using FluentAssertions.Common;
+#if !NETSTANDARD2_0
 using FluentAssertions.Events;
+#endif
 using FluentAssertions.Numeric;
 using FluentAssertions.Primitives;
 using FluentAssertions.Reflection;
@@ -129,7 +131,7 @@ public static ExecutionTime ExecutionTime(this Func<Task> action)
 
         /// <summary>
         /// Returns an <see cref="ExecutionTimeAssertions"/> object that can be used to assert the
-        /// current <see cref="ExecutionTime"/>.
+        /// current <see cref="FluentAssertions.Specialized.ExecutionTime"/>.
         /// </summary>
         [Pure]
         public static ExecutionTimeAssertions Should(this ExecutionTime executionTime)
@@ -772,17 +774,18 @@ public static TTo As<TTo>(this object subject)
         }
 
         /// <summary>
-        /// Asserts that the thrown exception has a message that matches <paramref name = "expectedWildcardPattern" />.
+        /// Asserts that the thrown exception has a message that matches <paramref name="expectedWildcardPattern" />.
         /// </summary>
-        /// <param name = "expectedWildcardPattern">
+        /// <param name="task">The <see cref="ExceptionAssertions{TException}"/> containing the thrown exception.</param>
+        /// <param name="expectedWildcardPattern">
         /// The wildcard pattern with which the exception message is matched, where * and ? have special meanings.
         /// </param>
-        /// <param name = "because">
+        /// <param name="because">
         /// A formatted phrase as is supported by <see cref = "string.Format(string,object[])" /> explaining why the assertion
         /// is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
         /// </param>
-        /// <param name = "becauseArgs">
-        /// Zero or more objects to format using the placeholders in <see cref = "because" />.
+        /// <param name="becauseArgs">
+        /// Zero or more objects to format using the placeholders in <paramref name="because"/>.
         /// </param>
         public static async Task<ExceptionAssertions<TException>> WithMessage<TException>(
             this Task<ExceptionAssertions<TException>> task,

Src/FluentAssertions/CallerIdentifier.cs

@@ -155,6 +155,5 @@ private static bool IsBooleanLiteral(string candidate)
         {
             return candidate == "true" || candidate == "false";
         }
-
     }
 }

Src/FluentAssertions/Collections/CollectionAssertions.cs

@@ -1,7 +1,6 @@
 using System;
 using System.Collections;
 using System.Collections.Generic;
-using System.ComponentModel;
 using System.Linq;
 using System.Reflection;
 using FluentAssertions.Common;
@@ -321,6 +320,7 @@ public AndConstraint<TAssertions> NotEqual(IEnumerable unexpected, string becaus
         /// items in the collection are structurally equal.
         /// Notice that actual behavior is determined by the global defaults managed by <see cref="AssertionOptions"/>.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable{T}"/> with the expected elements.</param>
         /// <param name="because">
         /// An optional formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the
         /// assertion is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -365,6 +365,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(params object[] expectations)
         /// items in the collection are structurally equal.
         /// Notice that actual behavior is determined by the global defaults managed by <see cref="AssertionOptions"/>.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable"/> with the expected elements.</param>
         /// <param name="because">
         /// An optional formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the
         /// assertion is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -390,6 +391,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(IEnumerable expectation, string
         /// items in the collection are structurally equal.
         /// Notice that actual behavior is determined by the global defaults managed by <see cref="AssertionOptions"/>.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable"/> with the expected elements.</param>
         /// <param name="config">
         /// A reference to the <see cref="EquivalencyAssertionOptions{TSubject}"/> configuration object that can be used
         /// to influence the way the object graphs are compared. You can also provide an alternative instance of the
@@ -438,6 +440,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(IEnumerable expectation, string
         /// The type of a collection property is ignored as long as the collection implements <see cref="IEnumerable"/> and all
         /// items in the collection are structurally equal.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable{T}"/> with the expected elements.</param>
         /// <param name="config">
         /// A reference to the <see cref="EquivalencyAssertionOptions{TSubject}"/> configuration object that can be used
         /// to influence the way the object graphs are compared. You can also provide an alternative instance of the
@@ -550,6 +553,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(IEnumerable expectation, string
         /// and the result is equal.
         /// Notice that actual behavior is determined by the global defaults managed by <see cref="AssertionOptions"/>.
         /// </remarks>
+        /// <param name="expectation">The expected element.</param>
         /// <param name="because">
         /// An optional formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the
         /// assertion is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -572,6 +576,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(IEnumerable expectation, string
         /// and the result is equal.
         /// Notice that actual behavior is determined by the global defaults managed by <see cref="AssertionOptions"/>.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable{T}"/> with the expected elements.</param>
         /// <param name="config">
         /// A reference to the <see cref="EquivalencyAssertionOptions{TSubject}"/> configuration object that can be used
         /// to influence the way the object graphs are compared. You can also provide an alternative instance of the
@@ -1539,6 +1544,8 @@ public AndConstraint<TAssertions> EndWith(object element, string because = "", p
         /// <summary>
         /// Asserts that the <paramref name="expectation"/> element directly precedes the <paramref name="successor"/>.
         /// </summary>
+        /// <param name="successor">The element that should succeed <paramref name="expectation"/>.</param>
+        /// <param name="expectation">The expected element that should precede <paramref name="successor"/>.</param>
         /// <param name="because">
         /// A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
         /// is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -1582,6 +1589,8 @@ private object PredecessorOf(object successor, IEnumerable<object> subject)
         /// <summary>
         /// Asserts that the <paramref name="expectation"/> element directly succeeds the <paramref name="predecessor"/>.
         /// </summary>
+        /// <param name="predecessor">The element that should precede <paramref name="expectation"/>.</param>
+        /// <param name="expectation">The element that should succeed <paramref name="predecessor"/>.</param>
         /// <param name="because">
         /// A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
         /// is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.

Src/FluentAssertions/Collections/GenericDictionaryAssertions.cs

@@ -162,6 +162,7 @@ public GenericDictionaryAssertions(TCollection keyValuePairs)
         /// the values for each key are structurally equivalent. Notice that actual behavior is determined by the global
         /// defaults managed by the <see cref="AssertionOptions"/> class.
         /// </remarks>
+        /// <param name="expectation">The expected element.</param>
         /// <param name="because">
         /// An optional formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the
         /// assertion is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -186,6 +187,7 @@ public GenericDictionaryAssertions(TCollection keyValuePairs)
         /// the values for each key are structurally equivalent. Notice that actual behavior is determined by the global
         /// defaults managed by the <see cref="AssertionOptions"/> class.
         /// </remarks>
+        /// <param name="expectation">The expected element.</param>
         /// <param name="config">
         /// A reference to the <see cref="EquivalencyAssertionOptions{TSubject}"/> configuration object that can be used
         /// to influence the way the object graphs are compared. You can also provide an alternative instance of the

Src/FluentAssertions/Collections/SelfReferencingCollectionAssertions.cs

@@ -252,7 +252,7 @@ public AndConstraint<TAssertions> HaveCountLessOrEqualTo(int expected, string be
 
         /// <summary>
         /// Expects the current collection to contain all the same elements in the same order as the collection identified by
-        /// <paramref name="elements" />. Elements are compared using their <see cref="T.Equals(object)" /> method.
+        /// <paramref name="elements" />. Elements are compared using their <see cref="object.Equals(object)" /> method.
         /// </summary>
         /// <param name="elements">A params array with the expected elements.</param>
         public AndConstraint<TAssertions> Equal(params T[] elements)

Src/FluentAssertions/Collections/StringCollectionAssertions.cs

@@ -10,6 +10,9 @@ namespace FluentAssertions.Collections
     public class StringCollectionAssertions :
         StringCollectionAssertions<IEnumerable<string>>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="StringCollectionAssertions"/> class.
+        /// </summary>
         public StringCollectionAssertions(IEnumerable<string> actualValue)
             : base(actualValue)
         {
@@ -20,6 +23,9 @@ public class StringCollectionAssertions<TCollection> :
         StringCollectionAssertions<TCollection, StringCollectionAssertions<TCollection>>
         where TCollection : IEnumerable<string>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="StringCollectionAssertions{TCollection}"/> class.
+        /// </summary>
         public StringCollectionAssertions(TCollection actualValue)
             : base(actualValue)
         {
@@ -31,6 +37,9 @@ public class StringCollectionAssertions<TCollection, TAssertions> :
         where TCollection : IEnumerable<string>
         where TAssertions : StringCollectionAssertions<TCollection, TAssertions>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="StringCollectionAssertions{TCollection, TAssertions}"/> class.
+        /// </summary>
         public StringCollectionAssertions(TCollection actualValue)
             : base(actualValue)
         {
@@ -75,6 +84,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(params string[] expectation)
         /// <remarks>
         /// The two collections are equivalent when they both contain the same strings in any order.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable{String}"/> with the expected elements.</param>
         /// <param name="because">
         /// An optional formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the
         /// assertion is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
@@ -95,6 +105,7 @@ public AndConstraint<TAssertions> BeEquivalentTo(IEnumerable<string> expectation
         /// <remarks>
         /// The two collections are equivalent when they both contain the same strings in any order.
         /// </remarks>
+        /// <param name="expectation">An <see cref="IEnumerable{String}"/> with the expected elements.</param>
         /// <param name="config">
         /// A reference to the <see cref="EquivalencyAssertionOptions{String}"/> configuration object that can be used
         /// to influence the way the object graphs are compared. You can also provide an alternative instance of the
@@ -180,6 +191,9 @@ public AndConstraint<TAssertions> Contain(IEnumerable<string> expected)
         /// A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
         /// is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
         /// </param>
+        /// <param name="becauseArg">
+        /// An object to format using the placeholders in <paramref name="because" />.
+        /// </param>
         /// <param name="becauseArgs">
         /// Zero or more objects to format using the placeholders in <paramref name="because" />.
         /// </param>
@@ -201,6 +215,9 @@ public AndConstraint<TAssertions> Contain(IEnumerable<string> expected)
         /// A formatted phrase as is supported by <see cref="string.Format(string,object[])" /> explaining why the assertion
         /// is needed. If the phrase does not start with the word <i>because</i>, it is prepended automatically.
         /// </param>
+        /// <param name="becauseArg">
+        /// An object to format using the placeholders in <paramref name="because" />.
+        /// </param>
         /// <param name="becauseArgs">
         /// Zero or more objects to format using the placeholders in <paramref name="because" />.
         /// </param>

Src/FluentAssertions/Collections/WhichValueConstraint.cs

@@ -6,6 +6,9 @@ public class WhichValueConstraint<TCollection, TKey, TValue, TAssertions> : AndC
         where TCollection : IEnumerable<KeyValuePair<TKey, TValue>>
         where TAssertions : GenericDictionaryAssertions<TCollection, TKey, TValue, TAssertions>
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="WhichValueConstraint{TCollection, TKey, TValue, TAssertions}"/> class.
+        /// </summary>
         public WhichValueConstraint(TAssertions parentConstraint, TValue value)
             : base(parentConstraint)
         {

Src/FluentAssertions/Common/ConfigurationStoreExceptionInterceptor.cs

@@ -1,4 +1,4 @@
-
+#if NET47 || NETCOREAPP2_1 || NETCOREAPP3_0
 namespace FluentAssertions.Common
 {
     internal class ConfigurationStoreExceptionInterceptor : IConfigurationStore
@@ -31,4 +31,4 @@ public string GetSetting(string name)
         }
     }
 }
-
+#endif

Src/FluentAssertions/Common/NullConfigurationStore.cs

@@ -1,3 +1,4 @@
+#if !(NET47 || NETCOREAPP2_1 || NETCOREAPP3_0)
 namespace FluentAssertions.Common
 {
     internal class NullConfigurationStore : IConfigurationStore
@@ -8,3 +9,4 @@ public string GetSetting(string name)
         }
     }
 }
+#endif

Src/FluentAssertions/Equivalency/DictionaryEquivalencyStep.cs

@@ -1,6 +1,5 @@
 using System.Collections;
 using System.Diagnostics.CodeAnalysis;
-using System.Reflection;
 using FluentAssertions.Execution;
 
 namespace FluentAssertions.Equivalency

Src/FluentAssertions/Equivalency/EquivalencyValidationContext.cs

@@ -2,6 +2,9 @@
 
 namespace FluentAssertions.Equivalency
 {
+    /// <summary>
+    /// Provides information on a particular property during an assertion for structural equality of two object graphs.
+    /// </summary>
     public class EquivalencyValidationContext : IEquivalencyValidationContext
     {
         private Type compileTimeType;
@@ -19,12 +22,12 @@ public EquivalencyValidationContext()
         public string SelectedMemberDescription { get; set; }
 
         /// <summary>
-        /// Gets the value of the <see cref="IMemberInfo.SelectedMemberInfo" />
+        /// Gets the value of the subject object graph.
         /// </summary>
         public object Subject { get; set; }
 
         /// <summary>
-        /// Gets the value of the <see cref="IEquivalencyValidationContext.MatchingExpectationProperty" />.
+        /// Gets the value of the expected object graph..
         /// </summary>
         public object Expectation { get; set; }