From 0092b03d723203849cec9f7fa2964c7bd0dd05f0 Mon Sep 17 00:00:00 2001
From: Mohammadreza Taikandi <mrtaikandi@hotmail.com>
Date: Sun, 21 Feb 2021 08:18:42 +0000
Subject: [PATCH] Update to the latest changes.

---
 README.md | 113 ++++++++++++++++++++++++------------------------------
 1 file changed, 51 insertions(+), 62 deletions(-)

diff --git a/README.md b/README.md
index dde6dc5..0f21dd8 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,11 @@
 # MapTo
-![Nuget](https://img.shields.io/nuget/v/mapto?logo=nuget)
+[![Nuget](https://img.shields.io/nuget/v/mapto?logo=nuget)](https://www.nuget.org/packages/MapTo/)
 ![Publish Packages](https://github.com/mrtaikandi/MapTo/workflows/Publish%20Packages/badge.svg)
 
 A convention based object to object mapper using [Roslyn source generator](https://github.com/dotnet/roslyn/blob/master/docs/features/source-generators.md).
 
-MapTo creates mappings during compile-time, which eliminates the need for using reflection to create the mappings. This makes it super simple to use and way faster than other libraries.
+MapTo is a library to programmatically generate the necessary code to map one object to another during compile-time. It creates mappings during compile-time, eliminating the need to use reflection to map one object to another and make it simpler to use faster than other libraries at runtime.
+
 
 ## Installation
 ```
@@ -12,7 +13,7 @@ dotnet add package MapTo --prerelease
 ```
 
 ## Usage
-To generate the mappings, simply declare the destination class as `partial` and annotate it with `MapFrom` attribute.
+MapTo relies on a set of attributes to instruct it on how to generate the mappings. To start, declare the destination class as `partial`  and annotate it with `MapFrom` attribute. As its name implies, `MapFrom` attribute tells the library what the source class you want to map from is.
 
 ```c#
 using MapTo;
@@ -32,71 +33,59 @@ namespace App.ViewModels
 }
 ```
 
-## Generated Source
-In the above example, if `App.Data.Models.User` class is defined as:
-
-```c#
-namespace App.Data.Models
-{
-    public class User
-    {
-        public User(int id) => Id = id;
-        
-        public int Id { get; }
-
-        public string FirstName { get; set; }
-
-        public string LastName { get; set; }
-
-        public string FullName => $"{FirstName} {LastName}";
-    }
-}
-```
-
-It will generate the following code:
-
-```c#
-// <auto-generated />
-using System;
-
-namespace App.ViewModels
-{
-    public partial class UserViewModel
-    {
-        public UserViewModel(App.Data.Models.User user)
-        {
-            if (user == null) throw new ArgumentNullException(nameof(user));
-            
-            FirstName = user.FirstName;
-            LastName = user.LastName;
-        }
-
-        public static UserViewModel From(App.Data.Models.User user)
-        {
-            return user == null ? null : new UserViewModel(user);
-        }
-    }
-
-    public static partial class UserToUserViewModelExtensions
-    {
-        public static UserViewModel ToUserViewModel(this App.Data.Models.User user)
-        {
-            return user == null ? null : new UserViewModel(user);
-        }
-    }
-}
-```
-
-Which makes it possible to get an instance of `UserViewModel` from one of the following ways:
+To get an instance of `UserViewModel` from the `User` class, you can use any of the following methods:
 
 ```c#
 var user = new User(id: 10) { FirstName = "John", LastName = "Doe" };
 
-var vm = user.ToUserViewModel();
+var vm = user.ToUserViewModel(); // A generated extension method for User class.
 
 // OR
-vm = new UserViewModel(user);
+vm = new UserViewModel(user); // A generated contructor.
 
 // OR
-vm = UserViewModel.From(user);
+vm = UserViewModel.From(user); // A generated factory method.
+```
+
+> Please refer to [sample console app](https://github.com/mrtaikandi/MapTo/tree/master/test/TestConsoleApp) for a more complete example.
+
+## Available Attributes
+### IgnoreProperty
+By default, MapTo will include all properties with the same name (case-sensitive), whether read-only or not, in the mapping unless annotating them with the `IgnoreProperty` attribute.
+```c#
+[IgnoreProperty]
+public string FullName { get; set; }
+``` 
+
+### MapProperty
+This attribute gives you more control over the way the annotated property should get mapped. For instance, if the annotated property should use a property in the source class with a different name.
+
+```c#
+[MapProperty(SourcePropertyName = "Id")]
+public int Key { get; set; }
+```
+
+### MapTypeConverter
+A compilation error gets raised by default if the source and destination properties types are not implicitly convertible, but to convert the incompatible source type to the desired destination type, `MapTypeConverter` can be used.
+
+This attribute will accept a type that implements `ITypeConverter<in TSource, out TDestination>` interface.
+
+```c#
+[MapFrom(typeof(User))]
+public partial class UserViewModel
+{
+    public DateTimeOffset RegisteredAt { get; set; }
+    
+    [IgnoreProperty]
+    public ProfileViewModel Profile { get; set; }
+    
+    [MapTypeConverter(typeof(IdConverter))]
+    [MapProperty(SourcePropertyName = nameof(User.Id))]    
+    public string Key { get; }
+
+    private class IdConverter : ITypeConverter<int, string>
+    {
+        public string Convert(int source, object[] converterParameters) => $"{source:X}";
+    }
+}
 ```
\ No newline at end of file