chore(docs): update the documentation, add example

Author: Tieske

examples/errors.lua

@@ -0,0 +1,40 @@
+-- This example shows how to collect either the first error or all errors
+-- during validation.
+
+local jsonschema = require 'resty.ljsonschema'
+
+local my_schema = {
+    type = "object",
+    properties = {
+        name = {
+            type = "string",
+            minLength = 3
+        },
+        age = {
+            type = "integer",
+            minimum = 0
+        },
+        email = {
+            type = "string",
+            pattern = "^[^@]+@[^@]+$"
+        }
+    },
+    required = { "name", "age" }
+}
+
+-- Generate two validators: one that stops at the first error, and one that
+-- collects all errors.
+local validator_single = jsonschema.generate_validator(my_schema)
+local validator_all    = jsonschema.generate_validator(my_schema, { collect_all_errors = true })
+
+-- Now define values to validate against our spec:
+local my_data = {
+  name = 'Al',
+  age = -42.1,
+  email = 'invalid-email'
+}
+
+-- requires Penlight library for pretty printing tables
+local pl_pretty = require 'pl.pretty'
+print("single: " .. pl_pretty.write({validator_single(my_data)}))  --> false, error message
+print("all: " .. pl_pretty.write({validator_all(my_data)}))        --> false, table of all error messages

src/resty/ljsonschema/init.lua

@@ -1223,11 +1223,10 @@ local _M = {
   -- There is no default implementation: this function must be provided if
   -- resolving external schemas is required. The function signature should be: `function(url)`
   -- @tparam[opt] bool custom.collect_all_errors If set to true, the validator will collect all validation errors
-  -- instead of stopping at the first one. The error message contains:
-  -- * schema_path: Path to the JSON Schema keyword that failed validation.
-  -- * instance_path: Path to the value that failed validation.
-  -- * error: The error message.
-  --
+  -- instead of stopping at the first one. Each error entry contains:
+  -- `schema_path` (path to the JSON Schema keyword that failed validation),
+  -- `instance_path` (path to the value that failed validation), and
+  -- `error` (the error message).
   -- @tparam[opt=false] bool custom.coercion There are cases where incoming data will always be strings. For example
   -- when validating http-headers or query arguments.
   -- For these cases there is this option `coercion`. If you set this flag then