Adding support for `.example()` to document schema examples

[erunion]

I've added a new .example() method that, like .describe(), will allow consumers to document example values and representations of their schemas.

const documentedString = z
  .string()
  .url()
  .example("https://example.com")
  .example("https://example.local");

documentedString.examples; // ["https://example.com", "https://example.local"]

Like the JSON Schema examples array this currently has no type or shape restrictions. It may at some point be nice to restrict content being supplied to .example() to match the schema type (eg. only strings can be supplied on z.string()) but I've not (yet) done that here.

This work is being done to resolve https://github.com/colinhacks/zod/discussions/2266, and should, with a followup change to zod-to-json-schema[^1], allow Zod consumers to document schema examples within their generated JSON Schema representations.

[^1]: I plan on submitting a change to support examples to zod-to-json-schema after this work is in.