From 049b530d418b48a65aa539a35ca2194d826e9df3 Mon Sep 17 00:00:00 2001 From: Nate Wilcox Date: Mon, 22 May 2023 20:50:14 -0700 Subject: [PATCH 1/4] Extract `libipld` crate docs to `README-libipld.md` for nicer long-doc markup. --- README-libipld.md | 1 + src/lib.rs | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) create mode 100644 README-libipld.md diff --git a/README-libipld.md b/README-libipld.md new file mode 100644 index 00000000..fc52ff78 --- /dev/null +++ b/README-libipld.md @@ -0,0 +1 @@ +The `Ipld` crate. diff --git a/src/lib.rs b/src/lib.rs index b9b26978..017eb8ff 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,4 +1,4 @@ -//! The `Ipld` crate. +#![doc = include_str!("../README-libipld.md")] #![deny(missing_docs)] #![deny(warnings)] From a51668f48e431b01c00bdb550b473ee4d6bb71df Mon Sep 17 00:00:00 2001 From: Nate Wilcox Date: Mon, 22 May 2023 21:10:07 -0700 Subject: [PATCH 2/4] Start adding `libipld` crate docs that describe the relationship to `serde` and `self::codec`. --- README-libipld.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/README-libipld.md b/README-libipld.md index fc52ff78..de1c2842 100644 --- a/README-libipld.md +++ b/README-libipld.md @@ -1 +1,11 @@ -The `Ipld` crate. +The [Ipld] crate. + +*InterPlanetary Linked Data* (IPLD) is a data model to enable decentralized data structures that are universally addressable and linkable, which in turn will enable more decentralized applications; see [ipld.io/docs](https://ipld.io/docs/). + +The *Data Model* is decoupled from a particular *Codec* in IPLD; see [ipld.io/glossary](https://ipld.io/glossary/). + +# Serde Support + +In the rust ecosystem, the IPLD Data Model vs Codec distinction is very similar approach to [serde](https://serde.rs), and this crate can leverage `serde` for codecs via the `serde-codec` feature. The [*serde Data Model*](https://serde.rs/data-model.html#types) and the [*IPLD Data Model*](https://ipld.io/glossary/#data-model) are different: `serde` provides a wider range of data types, while it lacks the [`link` kind](https://ipld.io/glossary/#link) which is essential to IPLD's purpose. This crate uses a work-around by encoding `link` types via opaque byte sequences in the `serde` layer. + +This crate began with a separate codec API based on the [codec] module. This API in effect attempts to recreate all of `serde` with support for links which, while cleaner, requires much more effort rather than relying on `serde`. From d22de62d21c8bcfdacf5548d3ec013ccbe4fe832 Mon Sep 17 00:00:00 2001 From: Nate Wilcox Date: Mon, 22 May 2023 21:12:04 -0700 Subject: [PATCH 3/4] Point out `codec` is to-be-deprecated and recommend `serde-codec` feature. --- README-libipld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README-libipld.md b/README-libipld.md index de1c2842..b81d3e42 100644 --- a/README-libipld.md +++ b/README-libipld.md @@ -8,4 +8,4 @@ The *Data Model* is decoupled from a particular *Codec* in IPLD; see [ipld.io/gl In the rust ecosystem, the IPLD Data Model vs Codec distinction is very similar approach to [serde](https://serde.rs), and this crate can leverage `serde` for codecs via the `serde-codec` feature. The [*serde Data Model*](https://serde.rs/data-model.html#types) and the [*IPLD Data Model*](https://ipld.io/glossary/#data-model) are different: `serde` provides a wider range of data types, while it lacks the [`link` kind](https://ipld.io/glossary/#link) which is essential to IPLD's purpose. This crate uses a work-around by encoding `link` types via opaque byte sequences in the `serde` layer. -This crate began with a separate codec API based on the [codec] module. This API in effect attempts to recreate all of `serde` with support for links which, while cleaner, requires much more effort rather than relying on `serde`. +This crate began with a separate codec API based on the [codec] module. This API in effect attempts to recreate all of `serde` with support for links which, while cleaner, requires much more effort rather than relying on `serde`. The [codec] module will be deprecated (see [issue #164](https://github.com/ipld/libipld/issues/164)), so new applications should rely on the `serde-codec` feature. From 6910834b3c1a234d319b2b289b3cc6c3da00af41 Mon Sep 17 00:00:00 2001 From: Nate Wilcox Date: Mon, 22 May 2023 21:13:06 -0700 Subject: [PATCH 4/4] Point out `Ipld` represents the IPLD Data Model. --- README-libipld.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README-libipld.md b/README-libipld.md index b81d3e42..b0df28b1 100644 --- a/README-libipld.md +++ b/README-libipld.md @@ -2,7 +2,7 @@ The [Ipld] crate. *InterPlanetary Linked Data* (IPLD) is a data model to enable decentralized data structures that are universally addressable and linkable, which in turn will enable more decentralized applications; see [ipld.io/docs](https://ipld.io/docs/). -The *Data Model* is decoupled from a particular *Codec* in IPLD; see [ipld.io/glossary](https://ipld.io/glossary/). +The *Data Model* is decoupled from a particular *Codec* in IPLD; see [ipld.io/glossary](https://ipld.io/glossary/). The Data Model is represented by the [Ipld] rust enum. # Serde Support