docs: improve null option documentation clarity

- Clarify that null: true is the default behavior
- Condense option tables from 8 rows to 4 using "-" for irrelevant values
- Use consistent column order (default, enforce, null) across tables
- Improve wording for "Providing Defaults" section

Author: fahchen

README.md

@@ -95,7 +95,7 @@ end
 
 ### Providing Defaults
 
-Fields with defaults aren't nullable (no reason to be):
+Fields with defaults don't need to be nullable since they always have a value:
 
 ```elixir
 typed_structor do
@@ -128,12 +128,12 @@ end
 
 The interaction between `enforce`, `default`, and `null` follows this logic:
 
-| enforce | default | null    | Type includes nil? |
-|---------|---------|---------|-------------------|
-| false   | no      | true    | Yes (nullable)    |
-| false   | no      | false   | No                |
-| false   | yes     | -       | No                |
-| true    | -       | -       | No                |
+| `:default` | `:enforce` | `:null` | Type includes `nil`? |
+|------------|------------|---------|----------------------|
+| `unset`    | `false`    | `true`  | yes                  |
+| `unset`    | `false`    | `false` | no                   |
+| `set`      | -          | -       | no                   |
+| -          | `true`     | -       | no                   |
 
 This is particularly useful when modeling database records where some fields can be `nil`:
 

lib/typed_structor.ex

@@ -27,7 +27,7 @@ defmodule TypedStructor do
 
     * `:module` - if provided, a new submodule will be created with the struct.
     * `:enforce` - if `true`, the struct will enforce the keys, see `field/3` options for more information.
-    * `:null` - if `true`, all fields without a default value and not enforced will have `nil` added to their type.
+    * `:null` - if `true` (default), fields without a default value and not enforced will have `nil` added to their type. If `false`, prevents `nil` from being added.
     * `:definer` - the definer module to use to define the struct, record or exception. Defaults to `:defstruct`. It also accepts a macro that receives the definition struct and returns the AST. See definer section below.
     * `:type_kind` - the kind of type to use for the struct. Defaults to `type`, can be `opaque` or `typep`.
     * `:type_name` - the name of the type to use for the struct. Defaults to `t`.
@@ -238,19 +238,16 @@ defmodule TypedStructor do
     * `:default` - sets the default value for the field
     * `:enforce` - if set to `true`, enforces the field, and makes its type
       non-nullable if `:default` is not set
-    * `:null` - if set to `true`, makes the field type nullable
-      if `:default` is not set and `:enforce` is not set
+    * `:null` - when set to `true` (the default), allows `nil` to be added to the
+      field type when `:default` is not set and `:enforce` is not set; when set
+      to `false`, prevents `nil` from being added in that case
 
   > ### How `:default`, `:enforce` and `:null` affect `type` and `@enforce_keys` {: .tip}
 
   > | **`:default`** | **`:enforce`** | **`:null`** | **`type`**        | **`@enforce_keys`** |
   > | -------------- | -------------- | ----------- | ----------------- | ------------------- |
-  > | `set`          | `true`         | `true`      | `t()`             | `excluded`          |
-  > | `set`          | `true`         | `false`     | `t()`             | `excluded`          |
-  > | `set`          | `false`        | `true`      | `t()`             | `excluded`          |
-  > | `set`          | `false`        | `false`     | `t()`             | `excluded`          |
-  > | `unset`        | `true`         | `true`      | `t()`             | **`included`**      |
-  > | `unset`        | `true`         | `false`     | `t()`             | **`included`**      |
+  > | `set`          | -              | -           | `t()`             | `excluded`          |
+  > | `unset`        | `true`         | -           | `t()`             | **`included`**      |
   > | `unset`        | `false`        | `true`      | **`t() \\| nil`** | `excluded`          |
   > | `unset`        | `false`        | `false`     | `t()`             | `excluded`          |
   """