diff --git a/lib/oxsdatatypes/README.md b/lib/oxsdatatypes/README.md
index c5f35fff..b89bc272 100644
--- a/lib/oxsdatatypes/README.md
+++ b/lib/oxsdatatypes/README.md
@@ -19,6 +19,19 @@ use oxsdatatypes::Decimal;
 assert!(Decimal::from_str("22.2").unwrap() > Decimal::from_str("21").unwrap());
 ```
 
+Each datatype is represented by a Rust struct.
+
+Each datatype provides:
+* `FromStr` implementation to parse a datatype string serialization following its [lexical mapping](https://www.w3.org/TR/xmlschema11-2/#dt-lexical-mapping).
+* `Display` implementation to serialize a datatype following its [canonical mapping](https://www.w3.org/TR/xmlschema11-2/#dt-canonical-mapping).
+* `is_identical_with` method following its [identity relation](https://www.w3.org/TR/xmlschema11-2/#identity).
+* `PartialEq`, and `Eq` if possible, implementations following its [equality relation](https://www.w3.org/TR/xmlschema11-2/#equality).
+* `PartialOrd`, and `Ord` if possible, implementations following its [order relation](https://www.w3.org/TR/xmlschema11-2/#order).
+* `From` and `TryFrom` implementations to implement [XPath casting](https://www.w3.org/TR/xpath-functions-31/#casting).
+* Various methods implementing [XPath functions](https://www.w3.org/TR/xpath-functions/).
+* `from_be_bytes` and `to_be_bytes` methods for serialization.
+
+
 ## License
 
 This project is licensed under either of
diff --git a/lib/oxsdatatypes/src/date_time.rs b/lib/oxsdatatypes/src/date_time.rs
index 5c59652f..66829adb 100644
--- a/lib/oxsdatatypes/src/date_time.rs
+++ b/lib/oxsdatatypes/src/date_time.rs
@@ -12,6 +12,9 @@ use std::str::FromStr;
 use std::time::SystemTimeError;
 
 /// [XML Schema `dateTime` datatype](https://www.w3.org/TR/xmlschema11-2/#dateTime)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`]
+/// and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct DateTime {
     timestamp: Timestamp,
@@ -190,7 +193,7 @@ impl DateTime {
         }
     }
 
-    // [fn:adjust-dateTime-to-timezone](https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone)
+    /// [fn:adjust-dateTime-to-timezone](https://www.w3.org/TR/xpath-functions/#func-adjust-dateTime-to-timezone)
     #[inline]
     pub fn adjust(&self, timezone_offset: Option<TimezoneOffset>) -> Option<Self> {
         Some(Self {
@@ -256,6 +259,9 @@ impl fmt::Display for DateTime {
 }
 
 /// [XML Schema `time` datatype](https://www.w3.org/TR/xmlschema11-2/#time)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the date 1972-12-31, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct Time {
     timestamp: Timestamp,
@@ -446,6 +452,9 @@ impl fmt::Display for Time {
 }
 
 /// [XML Schema `date` datatype](https://www.w3.org/TR/xmlschema11-2/#date)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the time 00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct Date {
     timestamp: Timestamp,
@@ -633,6 +642,9 @@ impl fmt::Display for Date {
 }
 
 /// [XML Schema `gYearMonth` datatype](https://www.w3.org/TR/xmlschema11-2/#gYearMonth)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the day-time 31T00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct GYearMonth {
     timestamp: Timestamp,
@@ -752,6 +764,9 @@ impl fmt::Display for GYearMonth {
 }
 
 /// [XML Schema `gYear` datatype](https://www.w3.org/TR/xmlschema11-2/#gYear)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the month-day-time 12-31T00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct GYear {
     timestamp: Timestamp,
@@ -870,6 +885,9 @@ impl fmt::Display for GYear {
 }
 
 /// [XML Schema `gMonthDay` datatype](https://www.w3.org/TR/xmlschema11-2/#gMonthDay)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the year 1972 and the time 31T00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct GMonthDay {
     timestamp: Timestamp,
@@ -985,6 +1003,9 @@ impl fmt::Display for GMonthDay {
 }
 
 /// [XML Schema `gMonth` datatype](https://www.w3.org/TR/xmlschema11-2/#gMonth)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the year 1972 and the day-time 31T00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct GMonth {
     timestamp: Timestamp,
@@ -1108,6 +1129,9 @@ impl fmt::Display for GMonth {
 }
 
 /// [XML Schema `date` datatype](https://www.w3.org/TR/xmlschema11-2/#date)
+///
+/// It encodes the value using a number of seconds from the Gregorian calendar era using a [`Decimal`],
+/// when combined with the year-month 1972-12 and the 00:00:00, and an optional timezone offset in minutes.
 #[derive(Eq, PartialEq, PartialOrd, Debug, Clone, Copy, Hash)]
 pub struct GDay {
     timestamp: Timestamp,
diff --git a/lib/oxsdatatypes/src/decimal.rs b/lib/oxsdatatypes/src/decimal.rs
index e710707b..3b6ea6af 100644
--- a/lib/oxsdatatypes/src/decimal.rs
+++ b/lib/oxsdatatypes/src/decimal.rs
@@ -13,6 +13,8 @@ const DECIMAL_PART_HALF_POW: i128 = 1_000_000_000;
 /// [XML Schema `decimal` datatype](https://www.w3.org/TR/xmlschema11-2/#decimal)
 ///
 /// It stores the decimal in a fix point encoding allowing nearly 18 digits before and 18 digits after ".".
+///
+/// It stores the value in a [`i128`] integer after multiplying it by 10¹⁸.
 #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)]
 pub struct Decimal {
     value: i128, // value * 10^18
diff --git a/lib/oxsdatatypes/src/double.rs b/lib/oxsdatatypes/src/double.rs
index b49410a4..6b5f10b9 100644
--- a/lib/oxsdatatypes/src/double.rs
+++ b/lib/oxsdatatypes/src/double.rs
@@ -8,6 +8,8 @@ use std::str::FromStr;
 /// [XML Schema `double` datatype](https://www.w3.org/TR/xmlschema11-2/#double)
 ///
 /// Uses internally a [`f64`].
+///
+/// Beware: serialization is currently buggy and do not follow the canonical mapping yet.
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 #[repr(transparent)]
 pub struct Double {
diff --git a/lib/oxsdatatypes/src/duration.rs b/lib/oxsdatatypes/src/duration.rs
index 386fd599..6998164e 100644
--- a/lib/oxsdatatypes/src/duration.rs
+++ b/lib/oxsdatatypes/src/duration.rs
@@ -9,7 +9,7 @@ use std::time::Duration as StdDuration;
 
 /// [XML Schema `duration` datatype](https://www.w3.org/TR/xmlschema11-2/#duration)
 ///
-/// It stores the duration using a pair of a `YearMonthDuration` and a `DayTimeDuration`.
+/// It stores the duration using a pair of a [`YearMonthDuration`] and a [`DayTimeDuration`].
 #[derive(Eq, PartialEq, Debug, Clone, Copy, Hash, Default)]
 pub struct Duration {
     year_month: YearMonthDuration,
@@ -238,7 +238,7 @@ impl Neg for Duration {
 
 /// [XML Schema `yearMonthDuration` datatype](https://www.w3.org/TR/xmlschema11-2/#yearMonthDuration)
 ///
-/// It stores the duration as a number of months encoded using a `i64`
+/// It stores the duration as a number of months encoded using a [`i64`].
 #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)]
 pub struct YearMonthDuration {
     months: i64,
@@ -389,7 +389,7 @@ impl Neg for YearMonthDuration {
 
 /// [XML Schema `dayTimeDuration` datatype](https://www.w3.org/TR/xmlschema11-2/#dayTimeDuration)
 ///
-/// It stores the duration as a number of seconds encoded using a `Decimal`
+/// It stores the duration as a number of seconds encoded using a [`Decimal`].
 #[derive(Eq, PartialEq, Ord, PartialOrd, Debug, Clone, Copy, Hash, Default)]
 pub struct DayTimeDuration {
     seconds: Decimal,
diff --git a/lib/oxsdatatypes/src/float.rs b/lib/oxsdatatypes/src/float.rs
index e94ff0aa..dde70893 100644
--- a/lib/oxsdatatypes/src/float.rs
+++ b/lib/oxsdatatypes/src/float.rs
@@ -8,6 +8,8 @@ use std::str::FromStr;
 /// [XML Schema `float` datatype](https://www.w3.org/TR/xmlschema11-2/#float)
 ///
 /// Uses internally a [`f32`].
+///
+/// Beware: serialization is currently buggy and do not follow the canonical mapping yet.
 #[derive(Debug, Clone, Copy, Default, PartialEq)]
 #[repr(transparent)]
 pub struct Float {
diff --git a/lib/oxsdatatypes/src/parser.rs b/lib/oxsdatatypes/src/parser.rs
index 1b056c07..22d652ea 100644
--- a/lib/oxsdatatypes/src/parser.rs
+++ b/lib/oxsdatatypes/src/parser.rs
@@ -16,6 +16,7 @@ use std::fmt;
 use std::num::ParseIntError;
 use std::str::FromStr;
 
+/// A parsing error
 #[derive(Debug, Clone)]
 pub struct XsdParseError {
     kind: XsdParseErrorKind,