fix README.md

Author: ddjerqq

README.md

@@ -9,24 +9,26 @@ adds support for data protection and querying for encrypted properties for your
 
 ## What problem does this library solve?
 
-When you need to store sensitive data in your database, you may want to encrypt it to protect it from unauthorized access. However, when you
-encrypt data, it becomes unreadable by EF-core, which is not really convenient if you want to encrypt, for example, email addresses, or SSNs
-AND then query them.
-This library (optionally) hashes the sensitive data and stores their sha256 hashes in a shadow property alongside the encrypted data. This
-allows you to query the encrypted data without decrypting it first. using `QueryableExt.WherePdEquals`
+When you need to store sensitive data in your database, you may want to encrypt it to protect it from unauthorized access, however, when you
+encrypt data, it becomes impossible to query it by EF-core, which is not really convenient if you want to encrypt, for example, email addresses, or SSNs
+AND then filter entities by them.
+This library (optionally) hashes the sensitive data and stores their sha256 hashes in a shadow property alongside the encrypted data. 
+This allows you to query the encrypted data without decrypting it first. using `QueryableExt.WherePdEquals`
 
 ## Disclaimer
 
-This project is maintained by <a href="https://github.com/ddjerqq">ddjerqq</a> and is not affiliated with Microsoft.
+This project is maintained by [one (tenx) developer](https://github.com/ddjerqq) and is not affiliated with Microsoft.
 
-I made this library initially to solve my own problems with EFCore when I needed to encrypt personal IDs but also query them. I wanted a
-simple yet boilerplate-free solution. Thus, I made this library.
+I made this library to solve my own problems with EFCore. I needed to store a bunch of protected personal data encrypted, among these properties were personal IDs, Emails, SocialSecurityNumbers and so on.
+As you know, you cannot query encrypted data with EFCore, and I wanted a simple yet boilerplate-free solution. Thus, I made this library.
+
+**What this library allows you to do, is to encrypt your properties and query them without decrypting them first. It does so by hashing the encrypted data and storing the hash in a shadow property alongside the encrypted data.**
 
 I **do not** take responsibility for any damage done in production environments and lose of your encryption key or corruption of your data.
 
 Keeping your encryption keys secure is your responsibility. If you lose your encryption key, **you will lose your data.**
 
-## Supported property types
+## Currently supported property types
 
 - string
 - byte[]
@@ -54,23 +56,23 @@ public class Your(DbContextOptions<Your> options, IDataProtectionProvider dataPr
     protected override void OnModelCreating(ModelBuilder builder)
     {
         // if you are using IEntityTypeConfiguration<T> in your project
-        // then ApplyConfigurationsFromAssembly must come before base.OnModelCreating(builder);
+        // then ApplyConfigurationsFromAssembly must come before base.OnModelCreating
         builder.ApplyConfigurationsFromAssembly(typeof(YourDbContext).Assembly);
 
         base.OnModelCreating(builder);
 
-        // MUST COME AFTER `base.OnModelCreating(builder);`
+        //      UseDataProtection MUST come after base.OnModelCreating
         builder.UseDataProtection(dataProtectionProvider);
 
-        // anything else you want to do with the builder must come after the call to UseDataProtection
+        // anything else you want to do with the builder must come after the call to UseDataProtection, unless you know exactly what you are doing
         builder.SnakeCaseRename();
     }
 }
 ```
 
 > [!WARNING]
-> The call to `builder.UseDataProtection` **MUST** come after the call to `base.OnModelCreating` in your `DbContext` class.
-> And before any other configuration you might have.
+> The call to `builder.UseDataProtection` **MUST** come after the call to `base.OnModelCreating` in your `DbContext` class
+> and before any other configuration you might have.
 
 ### Registering the services
 
@@ -86,7 +88,7 @@ builder.Services.AddDataProtectionServices()
 
 > [!TIP]
 > See the [Microsoft documentation](https://docs.microsoft.com/en-us/aspnet/core/security/data-protection/configuration/overview) for more
-> information on how to configure the data protection services, and how to store your encryption keys securely.
+> information on **how to configure the data protection** services, and how to store your encryption keys securely.
 
 ### Marking your properties as encrypted
 
@@ -96,19 +98,15 @@ Using the EncryptedAttribute:
 ```csharp
 class User
 {
-  public Guid Id { get; set; }
-
-  public string Name { get; set; }
-  
-  [Encrypt(true)]
+  [Encrypt(isQueryable: true)]
   public string SocialSecurityNumber { get; set; }
 
   [Encrypt]
   public byte[] IdPicture { get; set; }
 }
 ```
 
-Or using the FluentApi (in your `DbContext.OnModelCreating` method):
+Using the FluentApi (in your `DbContext.OnModelCreating` method):
 ```csharp
 protected override void OnModelCreating(ModelBuilder builder)
 {
@@ -120,7 +118,7 @@ protected override void OnModelCreating(ModelBuilder builder)
 }
 ```
 
-Or creating a custom `EntityTypeConfiguration`:
+Creating a custom `EntityTypeConfiguration` (Recommended for DDD):
 ```csharp
 class UserConfiguration : IEntityTypeConfiguration<User>
 {
@@ -142,14 +140,14 @@ var foo = await DbContext.Users
   .SingleOrDefaultAsync();
 ```
 
-> [!TIP]
-> Generates an expression like this under the hood:
-> `Where(e => EF.Property<string>(e, $"{propertyName}ShadowHash") == value.Sha256Hash())`
-
 > [!WARNING]
 > The `QueryableExt.WherePdEquals` method is only available for properties that are marked as Queryable using the `[Encrypt(isQueryable: true)]` attribute or the
 > `IsEncrypted(isQueryable: true)` method.
 
+> [!TIP]
+> The `WherePdEquals` extension method generates an expression like this one under the hood:<br/>
+> `Where(e => EF.Property<string>(e, $"{propertyName}ShadowHash") == value.Sha256Hash())`
+
 ### Profit!
 
 ## Thank you for using this library!