Document some more attributes

docs/1.1-attributes.md

@@ -17,6 +17,20 @@ You can add attributes to your types to customize Schemars's derived `JsonSchema
 
 Serde also allows setting `#[serde(...)]` attributes which change how types are serialized, and Schemars will generally respect these attributes to ensure that generated schemas will match how the type is serialized by serde_json. `#[serde(...)]` attributes can be overriden using `#[schemars(...)]` attributes, which behave identically (e.g. `#[schemars(rename_all = "camelCase")]`). You may find this useful if you want to change the generated schema without affecting Serde's behaviour, or if you're just not using Serde.
 
+## Table of Contents
+1. [Supported Serde Attributes](#supported-serde-attributes)
+    1. [`rename`](#rename)
+    1. [`rename_all`](#rename_all)
+    1. [`tag` / `untagged`](#tag)
+    1. [`default`](#default)
+    1. [`skip`](#skip)
+    1. [`skip_serializing`](#skip_serializing)
+    1. [`skip_deserializing`](#skip_deserializing)
+    1. [`flatten`](#flatten)
+    1. [`with`](#with)
+1. [Other Attributes](#other-attributes)
+    1. [Doc Comments (`doc`)](#doc)
+
 ## Supported Serde Attributes
 
 <div class="indented">
@@ -26,7 +40,7 @@ Serde also allows setting `#[serde(...)]` attributes which change how types are
 `#[serde(rename = "name")]` / `#[schemars(rename = "name")]`
 </h3>
 
-Set on a struct, enum, field or variant to use the given name in the generated schema instead of the Rust name. When used on a struct or enum, the given name will be used as the title for root schemas, and the schema identifier when the schema is referenced via a `$ref` schema property.
+Set on a struct, enum, field or variant to use the given name in the generated schema instead of the Rust name. When used on a struct or enum, the given name will be used as the title for root schemas, and as the schema identifier for schemas referenced from another schema's `$ref` property.
 
 Serde docs: [container](https://serde.rs/container-attrs.html#rename) / [variant](https://serde.rs/variant-attrs.html#rename) / [field](https://serde.rs/field-attrs.html#rename)
 
@@ -35,7 +49,7 @@ Serde docs: [container](https://serde.rs/container-attrs.html#rename) / [variant
 `#[serde(rename_all = "...")]` / `#[schemars(rename_all = "...")]`
 </h3>
 
-Set on a struct, enum or variant to rename all fields according to the given case convention.
+Set on a struct, enum or variant to rename all fields according to the given case convention (see the Serde docs for details).
 
 Serde docs: [container](https://serde.rs/container-attrs.html#rename_all) / [variant](https://serde.rs/variant-attrs.html#rename_all)
 
@@ -53,24 +67,37 @@ Serde docs: [`tag`](https://serde.rs/container-attrs.html#tag) / [`untagged`](ht
 `#[serde(default)]` / `#[schemars(default)]` / `#[serde(default = "path")]` / `#[schemars(default = "path")]`
 </h3>
 
-- skip_serializing_if - only used for serializing defaults
+Set on a struct or field to give fields a default value, which excludes them from the schema's `required` properties. The default will also be set on the field's schema's `default` property, unless it is skipped by a [`#[serde(skip_serializing_if = "..."]`](https://serde.rs/field-attrs.html#skip_serializing_if) attribute on the field. If the field also has a [`#[serde(serialize_with = "..."]`](https://serde.rs/field-attrs.html#serialize_with) property set, then it will be used to serialize the default value.
-- serialize_with - only used for serializing defaults
+
+Serde docs: [container](https://serde.rs/container-attrs.html#default) / [field](https://serde.rs/field-attrs.html#default)
 
 <h3 id="skip">
 
 `#[serde(skip)]` / `#[schemars(skip)]`
 </h3>
 
+Set on a variant or field to prevent it from appearing in any generated schema.
+
+Serde docs: [variant](https://serde.rs/variant-attrs.html#skip) / [field](https://serde.rs/field-attrs.html#skip)
+
 <h3 id="skip_serializing">
 
 `#[serde(skip_serializing)]` / `#[schemars(skip_serializing)]`
 </h3>
 
+Set on a field of a (non-tuple) struct to set the `writeOnly` property on that field's schema. Serde also allows this attribute on variants or tuple struct fields, but this will have no effect on generated schemas.
+
+Serde docs: [field](https://serde.rs/field-attrs.html#skip_deserializing)
+
 <h3 id="skip_deserializing">
 
 `#[serde(skip_deserializing)]` / `#[schemars(skip_deserializing)]`
 </h3>
 
+Set on a variant or field. When set on a field of a (non-tuple) struct, that field's schema will have the `readOnly` property set. When set on a variant or tuple struct field Schemars will treat this the same as a [`skip`](#skip) attribute.
+
+Serde docs: [variant](https://serde.rs/variant-attrs.html#skip_deserializing) / [field](https://serde.rs/field-attrs.html#skip_deserializing)
+
 <h3 id="flatten">
 
 `#[serde(flatten)]` / `#[schemars(flatten)]`
@@ -84,4 +111,10 @@ Serde docs: [`tag`](https://serde.rs/container-attrs.html#tag) / [`untagged`](ht
 </div>
 
 ## Other Attributes
-- doc
+
+<h3 id="doc">
+
+Doc Comments (`#[doc = "..."]`)
+</h3>
+
+TODO!