chore: add XML docs and test, improve README, add a few tests. (#2)

Author: dmytro-khmara

README.md

@@ -5,6 +5,8 @@ Timecop is a small library that helps you test DateTime in a static, thread-safe
 
 Timecop targets .NET Standard 2.0, has no external dependencies, and can be used with .NET Framework 4.5+ and any version of .NET and .NET Core.
 
+Timecop is the C# port of the [timecop](https://github.com/travisjeffery/timecop) Ruby gem.
+
 ## Installation
 
 You can install [Timecop](https://www.nuget.org/packages/Timecop/) from NuGet using the .NET CLI:
@@ -13,14 +15,9 @@ You can install [Timecop](https://www.nuget.org/packages/Timecop/) from NuGet us
 dotnet add package Timecop
 ```
 
-##  Usage
-
-Timecop allows freezing and travelling in time. It gives you two classes:
-1. `Clock` - use it instead of `DateTime.Now` and `DateTime.UtcNow`to get the current time
-2. `TimeCop`- use it to manipulate time in tests
-
+##  Basic usage
 
-Timecop can be used in a static context, the same way you would use DateTime:
+Timecop allows you to freeze and travel in time. Just use the `Clock` class instead of `DateTime`to get the current time via `Now` or `UtcNow` properties, and manipulate time with the `Timecop` class in your tests.
 
 ```csharp
 string Greet()
@@ -35,17 +32,63 @@ string Greet()
 
     return $"Good {timeOfDay}!";
 }
-
-using var tc = Timecop.Frozen(o => o.At(14,0,0).LocalTime());
+// freeze at 2pm local time:
+using var tc = Timecop.Frozen(o => o.At(14,0,0).LocalTime()); 
 
 Greet(); // Good afternoon!
-
-tc.TravelBy(TimeSpan.FromHours(6)); // travel to 8pm local time
+// travel to 8pm local time:
+tc.TravelBy(TimeSpan.FromHours(6)); 
 
 Greet(); // Good evening!
 ```
 
+## Available methods
+
+### Freezing and resuming time
+
+Time is frozen with either an instance `Freeze` or a static `Frozen` method, both having the same set of signatures. The instance `Freeze` freezes the instance of `Timecop`, the static `Frozen` creates an already frozen instance.
+
+Frozen time doesn't run for your tests unless you call `Resume` or dispose the `Timecop` instance:
+
+```csharp
+using var tc = Timecop.Frozen(1990, 12, 2, 14, 38, 51, DateTimeKind.Local);
+Clock.Now; // 1990-12-02 14:38:51
+
+Thread.Sleep(TimeSpan.FromSeconds(3));
+Clock.Now; // 1990-12-02 14:38:51 - Still the same value
+
+tc.Resume();
+
+Thread.Sleep(TimeSpan.FromSeconds(3));
+Clock.Now; // 1990-12-02 14:38:54 - Time has changed
+```
+
+Both `Freeze` and `Frozen` have the multiple overloads:
 
+```csharp
+// freeze at the current instant:
+tc.Freeze();
+// freeze at the specified DateTime:
+tc.Freeze(new DateTime(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc));
+// freeze at the specified date and time:
+tc.Freeze(1990, 12, 2, 14, 38, 51, DateTimeKind.Utc);
+// freeze at the specified date:
+tc.Freeze(1990, 12, 2, DateTimeKind.Utc);
+// freeze at the specified date or time or both:
+tc.Freeze(o => o.On(1990, 12, 2)
+                .At(14, 13, 51)
+                .LocalTime());
+```
+
+### Traveling in time
 
+Use  the `TravelBy` method to travel forward and backward in time:
 
+```csharp
+using var tc = Timecop.Frozen(1990, 12, 2, 14, 38, 51, DateTimeKind.Local);
+tc.TravelBy(TimeSpan.FromDays(1));
+Clock.Now; // 1990-12-03 14:38:51 - One day in the future
+```
+## License
 
+Timecop was created by [Dmytro Khmara](https://dmytrokhmara.com) and is licensed under the [MIT license](LICENSE.txt).

src/Timecop/DateTimeUtils/Builder/DatePart.cs

@@ -0,0 +1,16 @@
+namespace TCop.DateTimeUtils
+{
+    internal class DatePart
+    {
+        public int Year { get; }
+        public int Month { get; }
+        public int Day { get; }
+
+        public DatePart(int year, int month, int day)
+        {
+            Year = year;
+            Month = month;
+            Day = day;
+        }
+    }
+}

src/Timecop/DateTimeBuilder.cs …DateTimeUtils/Builder/DateTimeBuilder.cssrc/Timecop/DateTimeBuilder.cs renamed to src/Timecop/DateTimeUtils/Builder/DateTimeBuilder.cs src/Timecop/DateTimeBuilder.cs renamed to src/Timecop/DateTimeUtils/Builder/DateTimeBuilder.cs

@@ -1,55 +1,14 @@
 using System;
 
-namespace TCop;
-
-
-public class DatePart
-{
-    public int Year { get; }
-    public int Month { get; }
-    public int Day { get; }
-
-    public DatePart(int year, int month, int day)
-    {
-        Year = year;
-        Month = month;
-        Day = day;
-    }
-}
-
-public class TimePart
-{
-    public int Hour { get; }
-    public int Minute { get; }
-    public int Second { get; }
-
-    public TimePart(int hour, int minute, int second)
-    {
-        Hour = hour;
-        Minute = minute;
-        Second = second;
-    }
-}
-
-public class DateTimeBuilderContext
-{
-    public DatePart? Date { get; set; }
-    public TimePart? Time { get; set; }
-
-    public DateTimeKind? Kind { get; set; }
-}
+namespace TCop.DateTimeUtils;
 
 public class DateTimeBuilder
 {
     private readonly DateTimeBuilderContext _context = new DateTimeBuilderContext();
 
-    public DateTimeBuilder()
-    {
-    }
-
-    public DateTimeBuilder At(int hour, int minute, int second)
+    public DateTimeBuilder At(int hour, int minute, int second, int millisecond = 0)
     {
-        _context.Time = new TimePart(hour, minute, second);
+        _context.Time = new TimePart(hour, minute, second, millisecond);
         return this;
     }
 
@@ -75,15 +34,15 @@ public DateTime Build()
     {
         if (_context.Kind == null || _context.Kind == DateTimeKind.Unspecified)
         {
-            throw new InvalidDateTimeKindException();
+            throw new DateTimeKindNotSpecifiedException();
         }
 
         var now = _context.Kind == DateTimeKind.Local ? DateTime.Now : DateTime.UtcNow;
 
         _context.Date ??= new DatePart(now.Year, now.Month, now.Day);
-        _context.Time ??= new TimePart(now.Hour, now.Minute, now.Second);
+        _context.Time ??= new TimePart(now.Hour, now.Minute, now.Second, now.Millisecond);
 
         return new DateTime(_context.Date.Year, _context.Date.Month, _context.Date.Day,
-            _context.Time.Hour, _context.Time.Minute, _context.Time.Second, _context.Kind.Value);
+            _context.Time.Hour, _context.Time.Minute, _context.Time.Second, _context.Time.Millisecond, _context.Kind.Value);
     }
 }

src/Timecop/DateTimeUtils/Builder/DateTimeBuilderContext.cs

@@ -0,0 +1,12 @@
+using System;
+
+namespace TCop.DateTimeUtils
+{
+    internal class DateTimeBuilderContext
+    {
+        public DatePart? Date { get; set; }
+        public TimePart? Time { get; set; }
+
+        public DateTimeKind? Kind { get; set; }
+    }
+}

src/Timecop/DateTimeUtils/Builder/DateTimeKindNotSpecifiedException.cs

@@ -0,0 +1,11 @@
+using System;
+
+namespace TCop.DateTimeUtils
+{
+    public class DateTimeKindNotSpecifiedException : Exception
+    {
+        public DateTimeKindNotSpecifiedException() : base($"Specify either {nameof(DateTimeBuilder.LocalTime)}() or {nameof(DateTimeBuilder.UtcTime)}() when configuring time to freeze.")
+        {
+        }
+    }
+}

src/Timecop/DateTimeUtils/Builder/TimePart.cs

@@ -0,0 +1,18 @@
+namespace TCop.DateTimeUtils
+{
+    internal class TimePart
+    {
+        public int Hour { get; }
+        public int Minute { get; }
+        public int Second { get; }
+        public int Millisecond { get; }
+
+        public TimePart(int hour, int minute, int second, int millisecond)
+        {
+            Hour = hour;
+            Minute = minute;
+            Second = second;
+            Millisecond = millisecond;
+        }
+    }
+}

src/Timecop/DateTimeUtils/InvalidDateTimeKindException.cs

@@ -0,0 +1,11 @@
+using System;
+
+namespace TCop.DateTimeUtils
+{
+    public class InvalidDateTimeKindException : Exception
+    {
+        public InvalidDateTimeKindException() : base("DateTimeKind.Unspecified is not supported. Use DateTimeKind.Utc or DateTimeKind.Local.")
+        {
+        }
+    }
+}

src/Timecop/UtcDateTime.cs src/Timecop/DateTimeUtils/UtcDateTime.cssrc/Timecop/UtcDateTime.cs renamed to src/Timecop/DateTimeUtils/UtcDateTime.cs

@@ -1,6 +1,6 @@
 using System;
 
-namespace TCop;
+namespace TCop.DateTimeUtils;
 
 public struct UtcDateTime
 {
@@ -15,11 +15,4 @@ public UtcDateTime(DateTime value)
 
         UtcValue = value.ToUniversalTime();
     }
-}
-
-public class InvalidDateTimeKindException : Exception
-{
-    public InvalidDateTimeKindException(): base("DateTimeKind.Unspecified is not supported. Use DateTimeKind.Utc or DateTimeKind.Local.")
-    {
-    }
 }