Skip to content

Commit

Permalink
Retire .xdoc XML documentation files (#916)
Browse files Browse the repository at this point in the history 
* Move `It.xdoc` contents into `It.cs`
* Move `Match.xdoc` contents into `Match.cs`
* Move `Mock.xdoc` contents into `Mock.cs`
* Move `Mock.Generic.xdoc` contents into `Mock.Generic.cs`
  • Loading branch information
@stakx
stakx authored Aug 31, 2019
1 parent 3024c61 commit fff9464
Show file tree
Hide file tree
Showing 9 changed files with 455 additions and 648 deletions.
102 changes: 92 additions & 10 deletions src/Moq/It.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,12 @@ public static class Ref<TValue>
/// <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"]/*'/>
/// <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>
public static TValue IsAny<TValue>()
{
if (typeof(TValue).IsTypeMatcher())
Expand Down Expand Up @@ -116,7 +121,22 @@ public static TValue IsNotNull<TValue>()
/// <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"]/*'/>
/// <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.
/// <code>
/// mock.Setup(x =&gt; x.Do(It.Is&lt;int&gt;(i =&gt; i % 2 == 0)))
/// .Returns(1);
/// </code>
/// </example>
/// <example>
/// This example shows how to throw an exception if the argument to the method
/// is a negative number:
/// <code>
/// mock.Setup(x =&gt; x.GetUser(It.Is&lt;int&gt;(i =&gt; i &lt; 0)))
/// .Throws(new ArgumentException());
/// </code>
/// </example>
[SuppressMessage("Microsoft.Design", "CA1006:DoNotNestGenericTypesInMemberSignatures")]
public static TValue Is<TValue>(Expression<Func<TValue, bool>> match)
{
Expand Down Expand Up @@ -145,7 +165,6 @@ public static TValue Is<TValue>(Expression<Func<TValue, bool>> match)
/// <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"]/*'/>
[EditorBrowsable(EditorBrowsableState.Advanced)]
public static TValue Is<TValue>(Expression<Func<object, Type, bool>> match)
{
Expand All @@ -163,7 +182,16 @@ public static TValue Is<TValue>(Expression<Func<object, Type, bool>> match)
/// <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"]/*'/>
/// <example>
/// The following example shows how to expect a method call with an integer argument
/// within the 0..100 range.
/// <code>
/// mock.Setup(x => x.HasInventory(
/// It.IsAny&lt;string&gt;(),
/// It.IsInRange(0, 100, Range.Inclusive)))
/// .Returns(false);
/// </code>
/// </example>
public static TValue IsInRange<TValue>(TValue from, TValue to, Range rangeKind)
where TValue : IComparable
{
Expand All @@ -189,7 +217,18 @@ public static TValue IsInRange<TValue>(TValue from, TValue to, Range rangeKind)
/// </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)"]/*'/>
/// <example>
/// The following example shows how to expect a method call with an integer argument
/// with value from a list.
/// <code>
/// var values = new List&lt;int&gt; { 1, 2, 3 };
///
/// mock.Setup(x => x.HasInventory(
/// It.IsAny&lt;string&gt;(),
/// It.IsIn(values)))
/// .Returns(false);
/// </code>
/// </example>
public static TValue IsIn<TValue>(IEnumerable<TValue> items)
{
return Match<TValue>.Create(value => items.Contains(value), () => It.IsIn(items));
Expand All @@ -200,7 +239,16 @@ public static TValue IsIn<TValue>(IEnumerable<TValue> items)
/// </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)"]/*'/>
/// <example>
/// The following example shows how to expect a method call with an integer argument
/// with a value of 1, 2, or 3.
/// <code>
/// mock.Setup(x => x.HasInventory(
/// It.IsAny&lt;string&gt;(),
/// It.IsIn(1, 2, 3)))
/// .Returns(false);
/// </code>
/// </example>
public static TValue IsIn<TValue>(params TValue[] items)
{
return Match<TValue>.Create(value => items.Contains(value), () => It.IsIn(items));
Expand All @@ -211,7 +259,18 @@ public static TValue IsIn<TValue>(params TValue[] items)
/// </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)"]/*'/>
/// <example>
/// The following example shows how to expect a method call with an integer argument
/// with value not found from a list.
/// <code>
/// var values = new List&lt;int&gt; { 1, 2, 3 };
///
/// mock.Setup(x => x.HasInventory(
/// It.IsAny&lt;string&gt;(),
/// It.IsNotIn(values)))
/// .Returns(false);
/// </code>
/// </example>
public static TValue IsNotIn<TValue>(IEnumerable<TValue> items)
{
return Match<TValue>.Create(value => !items.Contains(value), () => It.IsNotIn(items));
Expand All @@ -222,7 +281,16 @@ public static TValue IsNotIn<TValue>(IEnumerable<TValue> items)
/// </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)"]/*'/>
/// <example>
/// The following example shows how to expect a method call with an integer argument
/// of any value except 1, 2, or 3.
/// <code>
/// mock.Setup(x => x.HasInventory(
/// It.IsAny&lt;string&gt;(),
/// It.IsNotIn(1, 2, 3)))
/// .Returns(false);
/// </code>
/// </example>
public static TValue IsNotIn<TValue>(params TValue[] items)
{
return Match<TValue>.Create(value => !items.Contains(value), () => It.IsNotIn(items));
Expand All @@ -232,7 +300,14 @@ public static TValue IsNotIn<TValue>(params TValue[] items)
/// 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)"]/*'/>
/// <example>
/// The following example shows how to expect a call to a method where the string argument
/// matches the given regular expression:
/// <code>
/// mock.Setup(x => x.Check(It.IsRegex("[a-z]+")))
/// .Returns(1);
/// </code>
/// </example>
public static string IsRegex(string regex)
{
Guard.NotNull(regex, nameof(regex));
Expand All @@ -249,7 +324,14 @@ public static string IsRegex(string regex)
/// </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)"]/*'/>
/// <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:
/// <code>
/// mock.Setup(x => x.Check(It.IsRegex("[a-z]+", RegexOptions.IgnoreCase)))
/// .Returns(1);
/// </code>
/// </example>
public static string IsRegex(string regex, RegexOptions options)
{
Guard.NotNull(regex, nameof(regex));
Expand Down
109 changes: 0 additions & 109 deletions src/Moq/It.xdoc
View file

This file was deleted.

42 changes: 41 additions & 1 deletion src/Moq/Match.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,47 @@ namespace Moq
/// Argument matching is used to determine whether a concrete invocation in the mock
/// matches a given setup. This matching mechanism is fully extensible.
/// </remarks>
/// <include file='Match.xdoc' path='docs/doc[@for="Match"]/*'/>
/// <example>
/// Creating a custom matcher is straightforward. You just need to create a method
/// that returns a value from a call to <see cref="Match.Create{T}(Predicate{T})"/>
/// with your matching condition and optional friendly render expression:
/// <code>
/// public Order IsBigOrder()
/// {
/// return Match.Create&lt;Order&gt;(
/// o => o.GrandTotal &gt;= 5000,
/// () => IsBigOrder()); // a friendly expression to render on failures
/// }
/// </code>
/// This method can be used in any mock setup invocation:
/// <code>
/// mock.Setup(m => m.Submit(IsBigOrder())
/// .Throws&lt;UnauthorizedAccessException&gt;();
/// </code>
/// At runtime, Moq knows that the return value was a matcher and
/// evaluates your predicate with the actual value passed into your predicate.
/// <para>
/// Another example might be a case where you want to match a lists of orders
/// that contains a particular one. You might create matcher like the following:
/// </para>
/// <code>
/// public static class Orders
/// {
/// public static IEnumerable&lt;Order&gt; Contains(Order order)
/// {
/// return Match.Create&lt;IEnumerable&lt;Order&gt;&gt;(orders => orders.Contains(order));
/// }
/// }
/// </code>
/// Now we can invoke this static method instead of an argument in an invocation:
/// <code>
/// var order = new Order { ... };
/// var mock = new Mock&lt;IRepository&lt;Order&gt;&gt;();
///
/// mock.Setup(x =&gt; x.Save(Orders.Contains(order)))
/// .Throws&lt;ArgumentException&gt;();
/// </code>
/// </example>
public abstract class Match : IMatcher
{
/// <devdoc>
Expand Down
47 changes: 0 additions & 47 deletions src/Moq/Match.xdoc
View file

This file was deleted.

Loading

0 comments on commit fff9464

Please sign in to comment.