diff --git a/serde/src/de/mod.rs b/serde/src/de/mod.rs index 6490fc2f..684c937d 100644 --- a/serde/src/de/mod.rs +++ b/serde/src/de/mod.rs @@ -148,6 +148,13 @@ macro_rules! declare_error_trait { /// /// Most deserializers should only need to provide the `Error::custom` method /// and inherit the default behavior for the other methods. + /// + /// # Example implementation + /// + /// The [example data format] presented on the website shows an error + /// type appropriate for a basic JSON data format. + /// + /// [example data format]: https://serde.rs/data-format.html pub trait Error: Sized $(+ $($supertrait)::+)* { /// Raised when there is general error when deserializing a type. /// @@ -873,6 +880,13 @@ where /// deserializer lifetimes] for a more detailed explanation of these lifetimes. /// /// [Understanding deserializer lifetimes]: https://serde.rs/lifetimes.html +/// +/// # Example implementation +/// +/// The [example data format] presented on the website contains example code for +/// a basic JSON `Deserializer`. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait Deserializer<'de>: Sized { /// The error type that can be returned if some error occurs during /// deserialization. @@ -1650,6 +1664,13 @@ pub trait Visitor<'de>: Sized { /// deserializer lifetimes] for a more detailed explanation of these lifetimes. /// /// [Understanding deserializer lifetimes]: https://serde.rs/lifetimes.html +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SeqAccess` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SeqAccess<'de> { /// The error type that can be returned if some error occurs during /// deserialization. @@ -1725,6 +1746,13 @@ where /// deserializer lifetimes] for a more detailed explanation of these lifetimes. /// /// [Understanding deserializer lifetimes]: https://serde.rs/lifetimes.html +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `MapAccess` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait MapAccess<'de> { /// The error type that can be returned if some error occurs during /// deserialization. @@ -1910,6 +1938,13 @@ where /// deserializer lifetimes] for a more detailed explanation of these lifetimes. /// /// [Understanding deserializer lifetimes]: https://serde.rs/lifetimes.html +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `EnumAccess` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait EnumAccess<'de>: Sized { /// The error type that can be returned if some error occurs during /// deserialization. @@ -1950,6 +1985,13 @@ pub trait EnumAccess<'de>: Sized { /// deserializer lifetimes] for a more detailed explanation of these lifetimes. /// /// [Understanding deserializer lifetimes]: https://serde.rs/lifetimes.html +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `VariantAccess` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait VariantAccess<'de>: Sized { /// The error type that can be returned if some error occurs during /// deserialization. Must match the error type of our `EnumAccess`. diff --git a/serde/src/ser/mod.rs b/serde/src/ser/mod.rs index f24de61a..34c8be9b 100644 --- a/serde/src/ser/mod.rs +++ b/serde/src/ser/mod.rs @@ -127,6 +127,13 @@ macro_rules! declare_error_trait { /// Trait used by `Serialize` implementations to generically construct /// errors belonging to the `Serializer` against which they are /// currently running. + /// + /// # Example implementation + /// + /// The [example data format] presented on the website shows an error + /// type appropriate for a basic JSON data format. + /// + /// [example data format]: https://serde.rs/data-format.html pub trait Error: Sized $(+ $($supertrait)::+)* { /// Used when a [`Serialize`] implementation encounters any error /// while serializing a type. @@ -309,6 +316,13 @@ pub trait Serialize { /// is the `serde_json::value::Serializer` (distinct from the main `serde_json` /// serializer) that produces a `serde_json::Value` data structure in memory as /// output. +/// +/// # Example implementation +/// +/// The [example data format] presented on the website contains example code for +/// a basic JSON `Serializer`. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait Serializer: Sized { /// The output type produced by this `Serializer` during successful /// serialization. Most serializers that produce text or binary output @@ -1520,6 +1534,8 @@ pub trait Serializer: Sized { /// Returned from `Serializer::serialize_seq`. /// +/// # Example use +/// /// ```rust /// # use std::marker::PhantomData; /// # @@ -1557,6 +1573,13 @@ pub trait Serializer: Sized { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeSeq` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeSeq { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1575,6 +1598,8 @@ pub trait SerializeSeq { /// Returned from `Serializer::serialize_tuple`. /// +/// # Example use +/// /// ```rust /// use serde::ser::{Serialize, Serializer, SerializeTuple}; /// @@ -1648,6 +1673,13 @@ pub trait SerializeSeq { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeTuple` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeTuple { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1666,6 +1698,8 @@ pub trait SerializeTuple { /// Returned from `Serializer::serialize_tuple_struct`. /// +/// # Example use +/// /// ```rust /// use serde::ser::{Serialize, Serializer, SerializeTupleStruct}; /// @@ -1684,6 +1718,13 @@ pub trait SerializeTuple { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeTupleStruct` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeTupleStruct { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1702,6 +1743,8 @@ pub trait SerializeTupleStruct { /// Returned from `Serializer::serialize_tuple_variant`. /// +/// # Example use +/// /// ```rust /// use serde::ser::{Serialize, Serializer, SerializeTupleVariant}; /// @@ -1733,6 +1776,13 @@ pub trait SerializeTupleStruct { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeTupleVariant` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeTupleVariant { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1751,6 +1801,8 @@ pub trait SerializeTupleVariant { /// Returned from `Serializer::serialize_map`. /// +/// # Example use +/// /// ```rust /// # use std::marker::PhantomData; /// # @@ -1790,6 +1842,13 @@ pub trait SerializeTupleVariant { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeMap` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeMap { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1853,6 +1912,8 @@ pub trait SerializeMap { /// Returned from `Serializer::serialize_struct`. /// +/// # Example use +/// /// ```rust /// use serde::ser::{Serialize, Serializer, SerializeStruct}; /// @@ -1875,6 +1936,13 @@ pub trait SerializeMap { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeStruct` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeStruct { /// Must match the `Ok` type of our `Serializer`. type Ok; @@ -1904,6 +1972,8 @@ pub trait SerializeStruct { /// Returned from `Serializer::serialize_struct_variant`. /// +/// # Example use +/// /// ```rust /// use serde::ser::{Serialize, Serializer, SerializeStructVariant}; /// @@ -1928,6 +1998,13 @@ pub trait SerializeStruct { /// } /// } /// ``` +/// +/// # Example implementation +/// +/// The [example data format] presented on the website demonstrates an +/// implementation of `SerializeStructVariant` for a basic JSON data format. +/// +/// [example data format]: https://serde.rs/data-format.html pub trait SerializeStructVariant { /// Must match the `Ok` type of our `Serializer`. type Ok;