From 5141270346d66ff93d635a183275300bb7eaf9b7 Mon Sep 17 00:00:00 2001 From: David Tolnay Date: Thu, 13 Apr 2017 11:52:33 -0700 Subject: [PATCH] Touch up the top-level documentation --- serde/src/lib.rs | 75 +++++++++++++++++++++++++++--------------------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/serde/src/lib.rs b/serde/src/lib.rs index 797cd86c..97df1cad 100644 --- a/serde/src/lib.rs +++ b/serde/src/lib.rs @@ -9,55 +9,64 @@ //! these two groups interact with each other, allowing any supported data //! structure to be serialized and deserialized using any supported data format. //! -//! See the Serde website https://serde.rs/ for additional documentation and +//! See the Serde website [https://serde.rs/] for additional documentation and //! usage examples. //! -//! ### Design +//! [https://serde.rs/]: https://serde.rs/ +//! +//! ## Design //! //! Where many other languages rely on runtime reflection for serializing data, //! Serde is instead built on Rust's powerful trait system. A data structure //! that knows how to serialize and deserialize itself is one that implements -//! Serde's `Serialize` and `Deserialize` traits (or uses Serde's code -//! generation to automatically derive implementations at compile time). This +//! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive +//! attribute to automatically generate implementations at compile time). This //! avoids any overhead of reflection or runtime type information. In fact in //! many situations the interaction between data structure and data format can //! be completely optimized away by the Rust compiler, leaving Serde -//! serialization to perform roughly the same speed as a handwritten serializer -//! for the specific selection of data structure and data format. +//! serialization to perform the same speed as a handwritten serializer for the +//! specific selection of data structure and data format. //! -//! ### Data formats +//! ## Data formats //! //! The following is a partial list of data formats that have been implemented //! for Serde by the community. //! -//! - [JSON](https://github.com/serde-rs/json), the ubiquitous JavaScript Object -//! Notation used by many HTTP APIs. -//! - [Bincode](https://github.com/TyOverby/bincode), a compact binary format +//! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs. +//! - [Bincode], a compact binary format //! used for IPC within the Servo rendering engine. -//! - [CBOR](https://github.com/pyfisch/cbor), a Concise Binary Object -//! Representation designed for small message size without the need for -//! version negotiation. -//! - [YAML](https://github.com/dtolnay/serde-yaml), a popular human-friendly -//! configuration language that ain't markup language. -//! - [MessagePack](https://github.com/3Hren/msgpack-rust), an efficient binary -//! format that resembles a compact JSON. -//! - [TOML](https://github.com/alexcrichton/toml-rs), a minimal configuration -//! format used by [Cargo](http://doc.crates.io/manifest.html). -//! - [Pickle](https://github.com/birkenfeld/serde-pickle), a format common in -//! the Python world. -//! - [Hjson](https://github.com/laktak/hjson-rust), a variant of JSON designed -//! to be readable and writable by humans. -//! - [BSON](https://github.com/zonyitoo/bson-rs), the data storage and network -//! transfer format used by MongoDB. -//! - [URL](https://github.com/nox/serde_urlencoded), the x-www-form-urlencoded -//! format. -//! - [XML](https://github.com/serde-rs/xml), the flexible machine-friendly W3C -//! standard. *(deserialization only)* -//! - [Envy](https://github.com/softprops/envy), a way to deserialize -//! environment variables into Rust structs. *(deserialization only)* -//! - [Redis](https://github.com/OneSignal/serde-redis), deserialize values from -//! Redis when using [redis-rs](https://crates.io/crates/redis). +//! - [CBOR], a Concise Binary Object Representation designed for small message +//! size without the need for version negotiation. +//! - [YAML], a popular human-friendly configuration language that ain't markup +//! language. +//! - [MessagePack], an efficient binary format that resembles a compact JSON. +//! - [TOML], a minimal configuration format used by [Cargo]. +//! - [Pickle], a format common in the Python world. +//! - [Hjson], a variant of JSON designed to be readable and writable by humans. +//! - [BSON], the data storage and network transfer format used by MongoDB. +//! - [URL], the x-www-form-urlencoded format. +//! - [XML], the flexible machine-friendly W3C standard. //! *(deserialization only)* +//! - [Envy], a way to deserialize environment variables into Rust structs. +//! *(deserialization only)* +//! - [Redis], deserialize values from Redis when using [redis-rs]. +//! *(deserialization only)* +//! +//! [JSON]: https://github.com/serde-rs/json +//! [Bincode]: https://github.com/TyOverby/bincode +//! [CBOR]: https://github.com/pyfisch/cbor +//! [YAML]: https://github.com/dtolnay/serde-yaml +//! [MessagePack]: https://github.com/3Hren/msgpack-rust +//! [TOML]: https://github.com/alexcrichton/toml-rs +//! [Pickle]: https://github.com/birkenfeld/serde-pickle +//! [Hjson]: https://github.com/laktak/hjson-rust +//! [BSON]: https://github.com/zonyitoo/bson-rs +//! [URL]: https://github.com/nox/serde_urlencoded +//! [XML]:https://github.com/RReverser/serde-xml-rs +//! [Envy]: https://github.com/softprops/envy +//! [Redis]: https://github.com/OneSignal/serde-redis +//! [Cargo]: http://doc.crates.io/manifest.html +//! [redis-rs]: https://crates.io/crates/redis #![doc(html_root_url = "https://docs.rs/serde/0.9.13")]