Skip to content

Commit 43f5eb5

Browse files
osiewiczosiewicz
committed
review: Bring back old doc comment for serde_core
1 parent 5fcfbed commit 43f5eb5

File tree

1 file changed

+8
-87
lines changed

1 file changed

+8
-87
lines changed

‎serde_core/src/lib.rs‎

Lines changed: 8 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,97 +1,18 @@
1-
//! # Serde
1+
//! # Serde Core
22
//!
33
//! Serde is a framework for ***ser***ializing and ***de***serializing Rust data
44
//! structures efficiently and generically.
55
//!
6-
//! The Serde ecosystem consists of data structures that know how to serialize
7-
//! and deserialize themselves along with data formats that know how to
8-
//! serialize and deserialize other things. Serde provides the layer by which
9-
//! these two groups interact with each other, allowing any supported data
10-
//! structure to be serialized and deserialized using any supported data format.
6+
//! `serde_core` provides essential traits and functions that form the backbone of Serde. It is intended for use by data format implementations;
7+
//! while it is possible to depend on `serde` crate in a crate that implements a data format,
8+
//! doing so means that the build of data format crate cannot start until serde_derive is done building (if that feature is enabled).
9+
//! Thus, implementing a data format in terms of serde_core and not of serde should improve compile times of users of your data format.
1110
//!
12-
//! See the Serde website <https://serde.rs/> for additional documentation and
13-
//! usage examples.
11+
//! Alternatively, as an user of data formats you could use `serde_core` instead of `serde` if you do not intend to enable derive feature on `serde`.
1412
//!
15-
//! ## Design
13+
//! If you're still unsure which crate to use, favor `serde` for the most straightforward experience.
14+
//! For more detailed information and usage examples, refer to Serde's documentation at <https://serde.rs/>.
1615
//!
17-
//! Where many other languages rely on runtime reflection for serializing data,
18-
//! Serde is instead built on Rust's powerful trait system. A data structure
19-
//! that knows how to serialize and deserialize itself is one that implements
20-
//! Serde's `Serialize` and `Deserialize` traits (or uses Serde's derive
21-
//! attribute to automatically generate implementations at compile time). This
22-
//! avoids any overhead of reflection or runtime type information. In fact in
23-
//! many situations the interaction between data structure and data format can
24-
//! be completely optimized away by the Rust compiler, leaving Serde
25-
//! serialization to perform the same speed as a handwritten serializer for the
26-
//! specific selection of data structure and data format.
27-
//!
28-
//! ## Data formats
29-
//!
30-
//! The following is a partial list of data formats that have been implemented
31-
//! for Serde by the community.
32-
//!
33-
//! - [JSON], the ubiquitous JavaScript Object Notation used by many HTTP APIs.
34-
//! - [Postcard], a no\_std and embedded-systems friendly compact binary format.
35-
//! - [CBOR], a Concise Binary Object Representation designed for small message
36-
//! size without the need for version negotiation.
37-
//! - [YAML], a self-proclaimed human-friendly configuration language that ain't
38-
//! markup language.
39-
//! - [MessagePack], an efficient binary format that resembles a compact JSON.
40-
//! - [TOML], a minimal configuration format used by [Cargo].
41-
//! - [Pickle], a format common in the Python world.
42-
//! - [RON], a Rusty Object Notation.
43-
//! - [BSON], the data storage and network transfer format used by MongoDB.
44-
//! - [Avro], a binary format used within Apache Hadoop, with support for schema
45-
//! definition.
46-
//! - [JSON5], a superset of JSON including some productions from ES5.
47-
//! - [URL] query strings, in the x-www-form-urlencoded format.
48-
//! - [Starlark], the format used for describing build targets by the Bazel and
49-
//! Buck build systems. *(serialization only)*
50-
//! - [Envy], a way to deserialize environment variables into Rust structs.
51-
//! *(deserialization only)*
52-
//! - [Envy Store], a way to deserialize [AWS Parameter Store] parameters into
53-
//! Rust structs. *(deserialization only)*
54-
//! - [S-expressions], the textual representation of code and data used by the
55-
//! Lisp language family.
56-
//! - [D-Bus]'s binary wire format.
57-
//! - [FlexBuffers], the schemaless cousin of Google's FlatBuffers zero-copy
58-
//! serialization format.
59-
//! - [Bencode], a simple binary format used in the BitTorrent protocol.
60-
//! - [Token streams], for processing Rust procedural macro input.
61-
//! *(deserialization only)*
62-
//! - [DynamoDB Items], the format used by [rusoto_dynamodb] to transfer data to
63-
//! and from DynamoDB.
64-
//! - [Hjson], a syntax extension to JSON designed around human reading and
65-
//! editing. *(deserialization only)*
66-
//! - [CSV], Comma-separated values is a tabular text file format.
67-
//!
68-
//! [JSON]: https://github.com/serde-rs/json
69-
//! [Postcard]: https://github.com/jamesmunns/postcard
70-
//! [CBOR]: https://github.com/enarx/ciborium
71-
//! [YAML]: https://github.com/dtolnay/serde-yaml
72-
//! [MessagePack]: https://github.com/3Hren/msgpack-rust
73-
//! [TOML]: https://docs.rs/toml
74-
//! [Pickle]: https://github.com/birkenfeld/serde-pickle
75-
//! [RON]: https://github.com/ron-rs/ron
76-
//! [BSON]: https://github.com/mongodb/bson-rust
77-
//! [Avro]: https://docs.rs/apache-avro
78-
//! [JSON5]: https://github.com/callum-oakley/json5-rs
79-
//! [URL]: https://docs.rs/serde_qs
80-
//! [Starlark]: https://github.com/dtolnay/serde-starlark
81-
//! [Envy]: https://github.com/softprops/envy
82-
//! [Envy Store]: https://github.com/softprops/envy-store
83-
//! [Cargo]: https://doc.rust-lang.org/cargo/reference/manifest.html
84-
//! [AWS Parameter Store]: https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html
85-
//! [S-expressions]: https://github.com/rotty/lexpr-rs
86-
//! [D-Bus]: https://docs.rs/zvariant
87-
//! [FlexBuffers]: https://github.com/google/flatbuffers/tree/master/rust/flexbuffers
88-
//! [Bencode]: https://github.com/P3KI/bendy
89-
//! [Token streams]: https://github.com/oxidecomputer/serde_tokenstream
90-
//! [DynamoDB Items]: https://docs.rs/serde_dynamo
91-
//! [rusoto_dynamodb]: https://docs.rs/rusoto_dynamodb
92-
//! [Hjson]: https://github.com/Canop/deser-hjson
93-
//! [CSV]: https://docs.rs/csv
94-
9516
////////////////////////////////////////////////////////////////////////////////
9617

9718
// Serde types in rustdoc of other crates get linked to here.

0 commit comments

Comments
 (0)