Clean up XML documentation (devlooped#843)

* Move all documentation except examples from `.xdoc` into `.cs` files
* Correct some typos and an inaccuracy

src/Moq/IMock.cs

@@ -11,18 +11,27 @@ namespace Moq
  /// </summary>
  public interface IMock<out T> where T : class
  {
- /// <include file='Mock.Generic.xdoc' path='docs/doc[@for="Mock{T}.Object"]/*'/>
+ /// <summary>
+ /// Exposes the mocked object instance.
+ /// </summary>
  [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Object", Justification = "Exposes the mocked object instance, so it's appropriate.")]
  [SuppressMessage("Microsoft.Naming", "CA1721:PropertyNamesShouldNotMatchGetMethods", Justification = "The public Object property is the only one visible to Moq consumers. The protected member is for internal use only.")]
  T Object { get; }
 
- /// <include file='Mock.xdoc' path='docs/doc[@for="Mock.Behavior"]/*'/>
+ /// <summary>
+ /// Behavior of the mock, according to the value set in the constructor.
+ /// </summary>
  MockBehavior Behavior { get; }
 
- /// <include file='Mock.xdoc' path='docs/doc[@for="Mock.CallBase"]/*'/>
+ /// <summary>
+ /// Whether the base member virtual implementation will be called for mocked classes if no setup is matched.
+ /// Defaults to <see langword="false"/>.
+ /// </summary>
  bool CallBase { get; set; }
 
- /// <include file='Mock.xdoc' path='docs/doc[@for="Mock.DefaultValue"]/*'/>
+ /// <summary>
+ /// Specifies the behavior to use when returning default values for unexpected invocations on loose mocks.
+ /// </summary>
  DefaultValue DefaultValue { get; set; }
  }
 }

src/Moq/It.cs

@@ -16,7 +16,14 @@
 
 namespace Moq
 {
- /// <include file='It.xdoc' path='docs/doc[@for="It"]/*'/>
+ /// <summary>
+ /// Allows the specification of a matching condition for an argument in a method invocation,
+ /// rather than a specific argument value. "It" refers to the argument being matched.
+ /// </summary>
+ /// <remarks>
+ /// This class allows the setup to match a method invocation with an arbitrary value,
+ /// with a value in a specified range, or even one that matches a given predicate.
+ /// </remarks>
  public static class It
  {
  /// <summary>
@@ -31,6 +38,13 @@ public static class Ref<TValue>
  public static TValue IsAny;
  }
 
+ /// <summary>
+ /// Matches any value of the given <typeparamref name="TValue"/> type.
+ /// </summary>
+ /// <typeparam name="TValue">Type of the value.</typeparam>
+ /// <remarks>
+ /// Typically used when the actual argument value for a method call is not relevant.
+ /// </remarks>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsAny"]/*'/>
  public static TValue IsAny<TValue>()
  {
@@ -51,7 +65,10 @@ internal static MethodCallExpression IsAny(Type genericArgument)
  return Expression.Call(It.isAnyMethod.MakeGenericMethod(genericArgument));
  }
 
- /// <include file='It.xdoc' path='docs/doc[@for="It.IsNotNull"]/*'/>
+ /// <summary>
+ /// Matches any value of the given <typeparamref name="TValue"/> type, except null.
+ /// </summary>
+ /// <typeparam name="TValue">Type of the value.</typeparam>
  public static TValue IsNotNull<TValue>()
  {
  return Match<TValue>.Create(
@@ -64,7 +81,14 @@ public static TValue IsNotNull<TValue>()
  () => It.IsNotNull<TValue>());
  }
 
-
+ /// <summary>
+ /// Matches any value that satisfies the given predicate.
+ /// </summary>
+ /// <param name="match">The predicate used to match the method argument.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
+ /// <remarks>
+ /// Allows the specification of a predicate to perform matching of method call arguments.
+ /// </remarks>
  /// <include file='It.xdoc' path='docs/doc[@for="It.Is"]/*'/>
  [SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures")]
  public static TValue Is<TValue>(Expression<Func<TValue, bool>> match)
@@ -74,6 +98,13 @@ public static TValue Is<TValue>(Expression<Func<TValue, bool>> match)
  Expression.Lambda<Func<TValue>>(ItExpr.Is<TValue>(match)));
  }
 
+ /// <summary>
+ /// Matches any value that is in the range specified.
+ /// </summary>
+ /// <param name="from">The lower bound of the range.</param>
+ /// <param name="to">The upper bound of the range.</param>
+ /// <param name="rangeKind">The kind of range. See <see cref="Range"/>.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsInRange"]/*'/>
  public static TValue IsInRange<TValue>(TValue from, TValue to, Range rangeKind)
  where TValue : IComparable
@@ -95,30 +126,54 @@ public static TValue IsInRange<TValue>(TValue from, TValue to, Range rangeKind)
  () => It.IsInRange(from, to, rangeKind));
  }
 
+ /// <summary>
+ /// Matches any value that is present in the sequence specified.
+ /// </summary>
+ /// <param name="items">The sequence of possible values.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsIn(enumerable)"]/*'/>
  public static TValue IsIn<TValue>(IEnumerable<TValue> items)
  {
  return Match<TValue>.Create(value => items.Contains(value), () => It.IsIn(items));
  }
 
+ /// <summary>
+ /// Matches any value that is present in the sequence specified.
+ /// </summary>
+ /// <param name="items">The sequence of possible values.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsIn(params)"]/*'/>
  public static TValue IsIn<TValue>(params TValue[] items)
  {
  return Match<TValue>.Create(value => items.Contains(value), () => It.IsIn(items));
  }
 
+ /// <summary>
+ /// Matches any value that is not found in the sequence specified.
+ /// </summary>
+ /// <param name="items">The sequence of disallowed values.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsNotIn(enumerable)"]/*'/>
  public static TValue IsNotIn<TValue>(IEnumerable<TValue> items)
  {
  return Match<TValue>.Create(value => !items.Contains(value), () => It.IsNotIn(items));
  }
 
+ /// <summary>
+ /// Matches any value that is not found in the sequence specified.
+ /// </summary>
+ /// <param name="items">The sequence of disallowed values.</param>
+ /// <typeparam name="TValue">Type of the argument to check.</typeparam>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsNotIn(params)"]/*'/>
  public static TValue IsNotIn<TValue>(params TValue[] items)
  {
  return Match<TValue>.Create(value => !items.Contains(value), () => It.IsNotIn(items));
  }
 
+ /// <summary>
+ /// Matches a string argument if it matches the given regular expression pattern.
+ /// </summary>
+ /// <param name="regex">The pattern to use to match the string argument value.</param>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsRegex(regex)"]/*'/>
  public static string IsRegex(string regex)
  {
@@ -131,6 +186,11 @@ public static string IsRegex(string regex)
  return Match<string>.Create(value => value != null && re.IsMatch(value), () => It.IsRegex(regex));
  }
 
+ /// <summary>
+ /// Matches a string argument if it matches the given regular expression pattern.
+ /// </summary>
+ /// <param name="regex">The pattern to use to match the string argument value.</param>
+ /// <param name="options">The options used to interpret the pattern.</param>
  /// <include file='It.xdoc' path='docs/doc[@for="It.IsRegex(regex,options)"]/*'/>
  public static string IsRegex(string regex, RegexOptions options)
  {

src/Moq/It.xdoc

@@ -1,49 +1,14 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <docs>
- <doc for="It">
- <summary>
- Allows the specification of a matching condition for an
- argument in a method invocation, rather than a specific
- argument value. "It" refers to the argument being matched.
- </summary>
- <remarks>
- This class allows the setup to match a method invocation
- with an arbitrary value, with a value in a specified range, or
- even one that matches a given predicate.
- </remarks>
- </doc>
  <doc for="It.IsAny">
- <summary>
- Matches any value of the given <typeparamref name="TValue"/> type.
- </summary>
- <remarks>
- Typically used when the actual argument value for a method
- call is not relevant.
- </remarks>
  <example>
  <code>
  // Throws an exception for a call to Remove with any string value.
  mock.Setup(x => x.Remove(It.IsAny&lt;string&gt;())).Throws(new InvalidOperationException());
  </code>
  </example>
- <typeparam name="TValue">Type of the value.</typeparam>
- </doc>
- <doc for="It.IsNotNull">
- <summary>
- Matches any value of the given <typeparamref name="TValue"/> type, except null.
- </summary>
- <typeparam name="TValue">Type of the value.</typeparam>
  </doc>
  <doc for="It.Is">
- <summary>
- Matches any value that satisfies the given predicate.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="match">The predicate used to match the method argument.</param>
- <remarks>
- Allows the specification of a predicate to perform matching
- of method call arguments.
- </remarks>
  <example>
  This example shows how to return the value <c>1</c> whenever the argument to the
  <c>Do</c> method is an even number.
@@ -60,15 +25,6 @@
  </example>
  </doc>
  <doc for="It.IsInRange">
- <summary>
- Matches any value that is in the range specified.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="from">The lower bound of the range.</param>
- <param name="to">The upper bound of the range.</param>
- <param name="rangeKind">
- The kind of range. See <see cref="Range"/>.
- </param>
  <example>
  The following example shows how to expect a method call
  with an integer argument within the 0..100 range.
@@ -81,11 +37,6 @@
  </example>
  </doc>
  <doc for="It.IsIn(enumerable)">
- <summary>
- Matches any value that is present in the sequence specified.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="items">The sequence of possible values.</param>
  <example>
  The following example shows how to expect a method call
  with an integer argument with value from a list.
@@ -100,11 +51,6 @@
  </example>
  </doc>
  <doc for="It.IsIn(params)">
- <summary>
- Matches any value that is present in the sequence specified.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="items">The sequence of possible values.</param>
  <example>
  The following example shows how to expect a method call
  with an integer argument with a value of 1, 2, or 3.
@@ -117,11 +63,6 @@
  </example>
  </doc>
  <doc for="It.IsNotIn(enumerable)">
- <summary>
- Matches any value that is not found in the sequence specified.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="items">The sequence of disallowed values.</param>
  <example>
  The following example shows how to expect a method call
  with an integer argument with value not found from a list.
@@ -136,11 +77,6 @@
  </example>
  </doc>
  <doc for="It.IsNotIn(params)">
- <summary>
- Matches any value that is not found in the sequence specified.
- </summary>
- <typeparam name="TValue">Type of the argument to check.</typeparam>
- <param name="items">The sequence of disallowed values.</param>
  <example>
  The following example shows how to expect a method call
  with an integer argument of any value except 1, 2, or 3.
@@ -153,10 +89,6 @@
  </example>
  </doc>
  <doc for="It.IsRegex(regex)">
- <summary>
- Matches a string argument if it matches the given regular expression pattern.
- </summary>
- <param name="regex">The pattern to use to match the string argument value.</param>
  <example>
  The following example shows how to expect a call to a method where the
  string argument matches the given regular expression:
@@ -166,11 +98,6 @@
  </example> 
  </doc>
  <doc for="It.IsRegex(regex,options)">
- <summary>
- Matches a string argument if it matches the given regular expression pattern.
- </summary>
- <param name="regex">The pattern to use to match the string argument value.</param>
- <param name="options">The options used to interpret the pattern.</param>
  <example>
  The following example shows how to expect a call to a method where the
  string argument matches the given regular expression, in a case insensitive way:

src/Moq/Linq/Mock.cs

@@ -14,7 +14,7 @@ namespace Moq
  public partial class Mock
  {
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
  /// <returns>The mocked object created.</returns>
@@ -24,7 +24,7 @@ public static T Of<T>() where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="behavior">Behavior of the mock.</param>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
@@ -46,7 +46,7 @@ public static T Of<T>(MockBehavior behavior) where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="predicate">The predicate with the specification of how the mocked object should behave.</param>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
@@ -58,7 +58,7 @@ public static T Of<T>(Expression<Func<T, bool>> predicate) where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="predicate">The predicate with the specification of how the mocked object should behave.</param>
  /// <param name="behavior">Behavior of the mock.</param>

src/Moq/Linq/MockRepository.cs

@@ -65,7 +65,7 @@ public IQueryable<T> Of<T>(Expression<Func<T, bool>> specification, MockBehavior
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
  /// <returns>The mocked object created.</returns>
@@ -76,7 +76,7 @@ public T OneOf<T>() where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="behavior">Behavior of the mock.</param>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
@@ -88,7 +88,7 @@ public T OneOf<T>(MockBehavior behavior) where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="specification">The predicate with the setup expressions.</param>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
@@ -101,7 +101,7 @@ public T OneOf<T>(Expression<Func<T, bool>> specification) where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="specification">The predicate with the setup expressions.</param>
  /// <param name="behavior">Behavior of the mock.</param>

src/Moq/Linq/Mocks.cs

@@ -66,7 +66,7 @@ public static IQueryable<T> Of<T>(Expression<Func<T, bool>> specification, MockB
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <typeparam name="T">The type of the mocked object.</typeparam>
  /// <returns>The mocked object created.</returns>
@@ -78,7 +78,7 @@ public static T OneOf<T>() where T : class
  }
 
  /// <summary>
- /// Creates an mock object of the indicated type.
+ /// Creates a mock object of the indicated type.
  /// </summary>
  /// <param name="specification">The predicate with the setup expressions.</param>
  /// <typeparam name="T">The type of the mocked object.</typeparam>