Skip to content

Add missing attribute documentation #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 4, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 62 additions & 8 deletions _src/container-attrs.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,30 @@
# Container attributes

- ##### `#[serde(rename = "name")]` {#rename}
-- `#[serde(rename(serialize = "ser_name"))]`
-- `#[serde(rename(deserialize = "de_name"))]`
-- `#[serde(rename(serialize = "ser_name", deserialize = "de_name"))]`

Serialize and deserialize this struct or enum with the given name instead of
its Rust name.

Also allows specifying an alternate name only when serializing, or only when
deserializing, or different alternate names for serializing and deserializing.

- ##### `#[serde(rename_all = "...")]` {#rename_all}
-- `#[serde(rename_all(serialize = "..."))]`
-- `#[serde(rename_all(deserialize = "..."))]`
-- `#[serde(rename_all(serialize = "...", deserialize = "..."))]`

Rename all the fields (if this is a struct) or variants (if this is an enum)
according to the given case convention. The possible values are `"lowercase"`,
`"UPPERCASE"`, `"PascalCase"`, `"camelCase"`, `"snake_case"`,
`"SCREAMING_SNAKE_CASE"`, `"kebab-case"`, `"SCREAMING-KEBAB-CASE"`.

Also allows specifying a case convention only when serializing, or only when
deserializing, or different case conventions for serializing and
deserializing.

- ##### `#[serde(deny_unknown_fields)]` {#deny_unknown_fields}

Always error during deserialization when encountering unknown fields. When
Expand All @@ -36,17 +49,16 @@
representations](enum-representations.md) for details on this representation.

- ##### `#[serde(bound = "T: MyTrait")]` {#bound}
-- `#[serde(bound(serialize = "T: MySerTrait"))]` {#bound--serialize}
-- `#[serde(bound(deserialize = "T: MyDeTrait"))]` {#bound--deserialize}
-- `#[serde(bound(serialize = "T: MySerTrait", deserialize = "T: MyDeTrait"))]`

Where-clause for the `Serialize` and `Deserialize` impls. This replaces any
Where-clause for the `Serialize` and/or `Deserialize` impls. This replaces any
trait bounds inferred by Serde.

- ##### `#[serde(bound(serialize = "T: MyTrait"))]` {#bound--serialize}

Where-clause for the `Serialize` impl.

- ##### `#[serde(bound(deserialize = "T: MyTrait"))]` {#bound--deserialize}

Where-clause for the `Deserialize` impl.
Allows specifying the same where-clause for serializing and deserializing; or
only specifying a where-clause for serializing, or deserializing; or
specifying different clauses for serializing and deserializing.

- ##### `#[serde(default)]` {#default}

Expand All @@ -71,3 +83,45 @@
Serialize and deserialize a newtype struct or a braced struct with one field
exactly the same as if its one field were serialized and deserialized by
itself. Analogous to `#[repr(transparent)]`.

- ##### `#[serde(crate = "...")]` {#crate}

Specify a path to the `serde` crate instance to use when deriving `Serialize`
and/or `Deserialize` for this type.

- ##### `#[serde(from = "FromType")]` {#from}

Deserialize this type by deserializing into `FromType`, then converting. This
type must implement `From<FromType>`, and `FromType` must implement
`Deserialize`.

- ##### `#[serde(into = "IntoType")]` {#into}

Serialize this type by converting it into the specified `IntoType` and
serializing that. This type must implement `Clone` and `Into<IntoType>`, and
`IntoType` must implement `Serialize`.

- ##### `#[serde(field_identifier)]` {#field_identifier}

Denotes that this enum represents the field names of a struct type. Used when
[manually implementing `Deserialize` for the struct
type.](deserialize_struct.md)

This attribute is probably not useful if you are automatically deriving your
own types.

Variants for the field_identifier enum may either all be units, or the last
variant may be a newtype struct, which is selected when an unlisted field name
is encountered during deserialization. Cannot be set if
`#[serde(variant_identifier)]` is also set.

- ##### `#[serde(variant_identifier)]` {#variant_identifier}

Denotes that this enum represents the variant names of another enum type.
Used when manually implementing `Deserialize` for the other enum type.

This attribute is probably not useful if you are automatically deriving your
own types.

Only valid for enums where all variants are units. Cannot be set if
`#[serde(field_identifier)]` is also set.
29 changes: 18 additions & 11 deletions _src/field-attrs.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,18 @@
# Field attributes

- ##### `#[serde(rename = "name")]` {#rename}
-- `#[serde(rename(serialize = "ser_name"))]`
-- `#[serde(rename(deserialize = "de_name"))]`
-- `#[serde(rename(serialize = "ser_name", deserialize = "de_name"))]`

Serialize and deserialize this field with the given name instead of its Rust
name. This is useful for [serializing fields as camelCase](attr-rename.md) or
serializing fields with names that are reserved Rust keywords.
Serialize and/or deserialize this field with the given name instead of its
Rust name. This is useful for
[serializing fields as camelCase](attr-rename.md) or serializing fields with
names that are reserved Rust keywords.

Allows specifying the same given name for serializing and deserializing; or
only specifying a given name for serializing, or for deserializing; or
specifying different given names for serializing and deserializing.

- ##### `#[serde(alias = "name")]` {#alias}

Expand Down Expand Up @@ -85,17 +93,16 @@
deserialization. See [this example](lifetimes.md#borrowing-data-in-a-derived-impl).

- ##### `#[serde(bound = "T: MyTrait")]` {#bound}
-- `#[serde(bound(serialize = "T: MySerTrait"))]` {#bound--serialize}
-- `#[serde(bound(deserialize = "T: MyDeTrait"))]` {#bound--deserialize}
-- `#[serde(bound(serialize = "T: MySerTrait", deserialize = "T: MyDeTrait"))]`

Where-clause for the `Serialize` and `Deserialize` impls. This replaces any
Where-clause for the `Serialize` and/or `Deserialize` impls. This replaces any
trait bounds inferred by Serde for the current field.

- ##### `#[serde(bound(serialize = "T: MyTrait"))]` {#bound--serialize}

Where-clause for the `Serialize` impl.

- ##### `#[serde(bound(deserialize = "T: MyTrait"))]` {#bound--deserialize}

Where-clause for the `Deserialize` impl.
Allows specifying the same where-clause for serializing and deserializing; or
only specifying a where-clause for serializing, or for deserializing; or
specifying different clauses for serializing and deserializing.

- ##### `#[serde(getter = "...")]` {#getter}

Expand Down
25 changes: 25 additions & 0 deletions _src/variant-attrs.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,35 @@
# Variant attributes

- ##### `#[serde(rename = "name")]` {#rename}
-- `#[serde(rename(serialize = "ser_name"))]`
-- `#[serde(rename(deserialize = "de_name"))]`
-- `#[serde(rename(serialize = "ser_name", deserialize = "de_name"))]`

Serialize and deserialize this variant with the given name instead of its Rust
name.

Also allows specifying an alternate name only when serializing, or only when
deserializing, or different alternate names for serializing and deserializing.

- ##### `#[serde(alias = "name")]` {#alias}

Deserialize this variant from the given name *or* from its Rust name. May be
repeated to specify multiple possible names for the same variant.

- ##### `#[serde(rename_all = "...")]` {#rename_all}
-- `#[serde(rename_all(serialize = "..."))]`
-- `#[serde(rename_all(deserialize = "..."))]`
-- `#[serde(rename_all(serialize = "...", deserialize = "..."))]`

Rename all the fields of this struct variant according to the given case
convention. The possible values are `"lowercase"`, `"UPPERCASE"`,
`"PascalCase"`, `"camelCase"`, `"snake_case"`, `"SCREAMING_SNAKE_CASE"`,
`"kebab-case"`, `"SCREAMING-KEBAB-CASE"`.

Also allows specifying a case convention only when serializing, or only when
deserializing, or different case conventions for serializing and
deserializing.

- ##### `#[serde(skip)]` {#skip}

Never serialize or deserialize this variant.
Expand Down Expand Up @@ -59,6 +72,18 @@
`$module::serialize` as the `serialize_with` function and
`$module::deserialize` as the `deserialize_with` function.

- ##### `#[serde(bound = "T: MyTrait")]` {#bound}
-- `#[serde(bound(serialize = "T: MySerTrait"))]` {#bound--serialize}
-- `#[serde(bound(deserialize = "T: MyDeTrait"))]` {#bound--deserialize}
-- `#[serde(bound(serialize = "T: MySerTrait", deserialize = "T: MyDeTrait"))]`

Where-clause for the `Serialize` and/or `Deserialize` impls. This replaces any
trait bounds inferred by Serde for the current variant.

Allows specifying the same where-clause for serializing and deserializing; or
only specifying a where-clause for serializing, or for deserializing; or
specifying different clauses for serializing and deserializing.

- ##### `#[serde(borrow)]` and `#[serde(borrow = "'a + 'b + ...")]` {#borrow}

Borrow data for this field from the deserializer by using zero-copy
Expand Down