Update README.md

README.md

@@ -7,63 +7,98 @@
 CodableKit is a Swift macro package designed to simplify the use of Swift's `Codable` protocol by allowing easy
 integration of default values, reducing the amount of auxiliary code you need to write.
 
-## How It Works
+## Features
 
-> This project is still under development, so the documentation is not complete, you may refer to the source code for
-> more details or peek the example below.
+- Custom coding keys
+- Default values for missing data
+- Handling of decoding failures
+- String to struct transcoding
+- Property ignoring
+- Explicit nil handling
+- Custom key property generation
 
-Just add the `@Codable` attribute to your structure. The macro automatically generates code to handle decoding and
-encoding in compliance with the Codable protocol, recognizing and neatly handling default values:
+## Usage
+
+To use the Codable macro, simply add the `@Codable` attribute to your struct declaration.
 
 ```swift
 @Codable
-struct User {
-  @CodableKey("uid") // Change the coding key to `uid`
-  let id: UUID
-  let name: String
-  var age: Int = 24
-
-  @CodableKey(options: .ignored) // Ignore this property
-  let thisPropertyWillNotBeIncluded: String
+struct Car {
+    let brand: String
+    let model: String
+    var year: Int = 2024
 }
 ```
 
-It gets transformed into:
+By setting the default value of the `year` property to 2024, the value will be 2024 when the raw data does not include that property.
+
+## Advanced Usage
+
+The Codable macro provides several additional features through the `@CodableKey` attribute and its associated options:
+
+*	**Custom Coding Keys**: Change the coding key for a property.
+
+```swift
+@CodableKey("uid")
+let id: UUID
+```
+
+* **CodableKeyOptions**: Customize the behavior of properties using various options.
+
+```swift
+@CodableKey(options: [.useDefaultOnFailure, .transcodeRawString])
+var someProperty: SomeType
+```
+
+> You can find the details in the [CodableKeyOptions.swift](Sources/CodableKitShared/CodableKeyOptions.swift) file.
+
+Available options:
+* `.default`: The default options (empty set).
+* `.ignored`: The property will be ignored during encoding and decoding.
+* `.explicitNil`: The key will be explicitly set to `nil` (`null`) when encoding and decoding, instead of being omitted.
+* `.generateCustomKey`: Generates a computed property to access the key when a custom CodableKey is used.
+* `.transcodeRawString`: Transcodes the value between raw string and the target type during encoding and decoding.
+* `.useDefaultOnFailure`: Uses the default value (if set) when decoding or encoding fails.
+
+## Example
+
+Here's a comprehensive example showcasing various features:
 
 ```swift
+@Codable
 struct User {
-  let id: UUID
-  let name: String
-  var age: Int = 24
+    @CodableKey("uid")
+    let id: UUID
+
+    let name: String
+
+    var age: Int = 24
 
-  let thisPropertyWillNotBeIncluded: String
-}
+    @CodableKey(options: .useDefaultOnFailure)
+    var avatar: URL? = nil
+
+    @CodableKey(options: .transcodeRawString)
+    var car: Car
+
+    @CodableKey(options: .ignored)
+    let thisPropertyWillNotBeIncluded: String
+
+    @CodableKey("custom_email", options: .generateCustomKey)
+    var email: String
 
-extension User: Codable {
-  enum CodingKeys: String, CodingKey {
-    case id = "uid"
-    case name
-    case age
-  }
-
-  init(from decoder: Decoder) throws {
-    let container = try decoder.container(keyedBy: CodingKeys.self)
-    id = try container.decode(UUID.self, forKey: .id)
-    name = try container.decode(String.self, forKey: .name)
-    age = try container.decodeIfPresent(Int.self, forKey: .age) ?? 24
-  }
-
-  func encode(to encoder: Encoder) throws {
-    var container = encoder.container(keyedBy: CodingKeys.self)
-    try container.encode(id, forKey: .id)
-    try container.encode(name, forKey: .name)
-    try container.encode(age, forKey: .age)
-  }
+    @CodableKey(options: .explicitNil)
+    var optionalField: String?
 }
 ```
 
-This lets you keep your models clean while the `@Codable` attribute generates the necessary Codable compliance code
-with incorporated default values in the background. Enjoy more streamlined Swift `Codable` handling with `CodableKit`.
+In this example:
+* `id` uses a custom coding key "uid".
+* `age` has a default value of 24.
+* `avatar` uses the default value if decoding fails.
+* `car` is transcoded from a raw string to the `Car` struct.
+* `thisPropertyWillNotBeIncluded` is ignored during encoding and decoding.
+* `email` uses a custom key "custom_email" and generates a computed property for access.
+* `optionalField` will be explicitly set to `null` when `nil`, instead of being omitted.
 
 ## Installation