docs: updated some missing docs for the v0.15 release

docs/docs/core-design-decisions.md

@@ -9,12 +9,14 @@ toc_max_heading_level: 4
 
 - All fields optinal by default. Same as graphql
 - When parsing into structs, private fields are ignored (same as stdlib json.Unmarshal)
-- The struct parser expects a `DataProvider` (although if you pass something else to the data field it will try to coerce it into a `DataProvider`), which is an interface that wraps around an input like a map. This is less efficient than doing it directly but allows us to reuse the same code for all kinds of data sources (i.e json, query params, forms, etc).
-- Errors returned by you can be the ZogError interface or an error. If you return an error, it will be wrapped in a ZogError. ZogError is just a struct that wraps around an error and adds a message field which is is text that can be shown to the user.
+- The struct parser expects a `DataProvider` (although if you pass something else to the data field it will try to coerce it into a `DataProvider`), which is an interface that wraps around an input like a map. This is less efficient than doing it directly but allows us to reuse the same code for all kinds of data sources (i.e json, query params, forms, etc). Generally as a normal user you should ignore that `DataProviders` exist. So forget you ever read this.
+- Errors returned by you (for example in a `PreTransform` or `PostTransform` function) can be the ZogError interface or an error. If you return an error, it will be wrapped in a ZogError. ZogError is just a struct that wraps around an error and adds a message field which is is text that can be shown to the user. For more on this see [Errors](/errors)
 - You should not depend on test execution order. They might run in parallel in the future
 
 > **A WORD OF CAUTION. ZOG & PANICS**
-> Zog will never panic due to invalid input but will always panic if invalid destination is passed to the `Parse` function (i.e if the destination does not match the schema).
+> In general Zog will never panic if the input data is wrong but it will panic if you configure it wrong. For example:
+> - In parse mode Zog will never panic due to invalid input data but will always panic if invalid destination is passed to the `Parse` function. if the destination does not match the schema in terms of types or fields.
+> - In validate mode Zog will panic if the expected types or fields are not present in the structure you are validating.
 
 ```go
 var schema = z.Struct(z.Schema{
@@ -25,21 +27,21 @@ type User struct {
   Name string
   Age int // age will be ignored since it is not a field in the schema
 }
-// this struct is not a valid destination for the schema. It is missing the name field. This will cause a panic even if the input data is map[string]any{"name": "zog"}
+// this struct is not a valid structure for the schema. It is missing the name field.
+// This will cause Zog to panic in both Parse and Validate mode
 type User2 struct {
   Email string,
   Age int
 }
+schema.Parse(map[string]any{"name": "zog"}, &User{}) // this will panic even if input data is valid. Because the destination is not a valid structure for the schema
+schema.Validate(&User2{}) // This will panic because the structure does not match the schema
 
 ```
 
 ## Limitations
 
 Most of these things are issues we would like to address in future versions.
 
-- Structs do not support pointers at the moment
-- slices do not support pointers
 - maps are not a supported schema type
 - structs and slices don't support catch, and structs don't suppoort default values
-- Validations and parsing cannot be run separately
 - It is not recommended to use very deeply nested schemas since that requires a lot of reflection and can have a negative impact on performance

docs/docs/getting-started.md

@@ -50,6 +50,7 @@ func main() {
   }
   u.Name // "Zog"
   // note that this might look weird but we didn't say age was required so Zog just skiped the empty string and we are left with the uninitialized int
+  // If we need 0 to be a valid value for age we can use a pointer to an int which will be nil if the value was not present in the input data
   u.Age // 0
 }
 ```

docs/docs/index.md

@@ -10,14 +10,15 @@ Killer Features:
 
 - Concise yet expressive schema interface, equipped to model simple to complex data models
 - **[Zod](https://github.com/colinhacks/zod)-like API**, use method chaining to build schemas in a typesafe manner
-- **Extensible**: add your own validators, schemas and data providers
-- Rich error details, make debugging a breeze
-- Almost no reflection when using primitive types
+- **Extensible**: add your own validators and schemas
+- **Rich errors** with detailed context, make debugging a breeze
+- **Fast**: No reflection when using primitive types
 - **Built-in coercion** support for most types
 - Zero dependencies!
-- **Three Helper Packages**
+- **Four Helper Packages**
   - **zenv**: parse environment variables
   - **zhttp**: parse http forms & query params
+  - **zjson**: parse json
   - **i18n**: Opinionated solution to good i18n zog errors
 
 > **API Stability:**

docs/docs/zog-schemas.md

@@ -19,7 +19,8 @@ schema.PreTransform(fn) // adds a pre-transformation function to the schema
 schema.PostTransform(fn) // adds a post-transformation function to the schema
 
 // VALIDATION METHODS
-schema.Parse(data, dest) // parses the data into the destination
+schema.Parse(data, destPtr) // parses the data into the destination
+schema.Validate(dataPtr) // validates the data structure directly. This is a pointer to a struct, slice, string, int, etc...
 ```
 
 ## Schema Types
@@ -37,7 +38,7 @@ z.Struct(z.Schema{
   "name": z.String(),
 })
 z.Slice(z.String())
-z.Ptr(z.String()) // validates pointer to string
+z.Ptr(z.String()) // pointer to string
 ```
 
 ## Primtive Types
@@ -97,7 +98,7 @@ z.Time().Before(time.Now()) // validates time is before now
 z.Time().Is(time.Now()) // validates time is equal to now
 
 // Schema Options
-z.Time(z.Time.Format(time.RFC3339)) // If input is a string, it will be parsed as a time.Time using the provided layout. time.RFC3339 is the default
+z.Time(z.Time.Format(time.RFC3339)) // If input is a string, it will be parsed as a time.Time using the provided layout. time.RFC3339 is the default. Keep in mind this coercion only works when using Parse()
 ```
 
 ## Complex Types
@@ -141,5 +142,5 @@ z.Ptr(z.String()) // validates pointer to string
 z.Ptr(z.Slice(z.String())) // validates pointer to slice of strings
 
 // Tests / Validators
-z.Ptr(z.String()).NotNil() // Validates pointer is not nil
+z.Ptr(z.String()).NotNil() // Validates pointer is not nil. This is equivalent to Required() for other types
 ```