update docs

src/de.rs

@@ -2,6 +2,16 @@
 //!
 //! This module provides [`from_str`] for deserializing Rust types from KDL text.
 //!
+//! Due to the fact that `serde` was developed with JSON in mind, and the incompatibility
+//! between KDL and JSON's data model, not all `serde` concepts apply smoothly to KDL. This
+//! leads to the fact that some KDL concepts are inexpressible in terms of `serde` derives
+//! and may require manual deserialization.
+//!
+//! The most notable restriction is the ability to distinguish between *arguments*,
+//! *properties* and *child nodes*, as JSON does not have such conception.
+//!
+//! Due to that the mapping is performed in a best effort manner.
+//!
 //! # KDL → Serde Data Model Mapping
 //!
 //! KDL documents are mapped to serde's data model as follows:
@@ -29,13 +39,97 @@
 //! }
 //!
 //! let kdl = r#"
-//! name "my-app"
+//! name my-app
 //! port 8080
 //! "#;
 //!
 //! let config: Config = kdl::de::from_str(kdl).unwrap();
 //! assert_eq!(config, Config { name: "my-app".into(), port: 8080 });
 //! ```
+//!
+//! ## Arguments mapping
+//!
+//! This library supports two kinds of special renaming for arguments - `#{n}` and `#args`:
+//!
+//! - `#{n}`: This is used when you want to access argument at a specific
+//!   position. The field name should start with `#`, then follow by the position
+//!   of the argument in numerical order starting from 0.
+//!
+//! ```rust
+//! use serde::Deserialize;
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Config {
+//!     server: Server,
+//! }
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Server {
+//!     #[serde(rename = "#0")]
+//!     name: String,
+//!     #[serde(rename = "#1")]
+//!     port: u16,
+//! }
+//!
+//! let kdl = r#"
+//! server my-app 8080
+//! "#;
+//!
+//! let config: Config = kdl::de::from_str(kdl).unwrap();
+//! assert_eq!(config, Config { server: Server { name: "my-app".into(), port: 8080 }});
+//! ```
+//!
+//! - `#args`: This is used when you want to collect *all* the arguments of the node.
+//!
+//! ```rust
+//! use serde::Deserialize;
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Config {
+//!     server: Server,
+//! }
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Server {
+//!     #[serde(rename = "#args")]
+//!     info: Vec<String>,
+//! }
+//!
+//! let kdl = r#"
+//! server my-app "https://example.com"
+//! "#;
+//!
+//! let config: Config = kdl::de::from_str(kdl).unwrap();
+//! assert_eq!(config, Config { server: Server { info: Vec::from(["my-app".into(), "https://example.com".into()]) }});
+//! ```
+//!
+//! ## Properties mapping
+//!
+//! You can use `#@field-name` on a field that will be used for a property.
+//!
+//! ```rust
+//! use serde::Deserialize;
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Config {
+//!     server: Server,
+//! }
+//!
+//! #[derive(Deserialize, Debug, PartialEq)]
+//! struct Server {
+//!     #[serde(rename = "#0")]
+//!     name: String,
+//!     #[serde(rename = "#@port")]
+//!     port: u16,
+//! }
+//!
+//! let kdl = r#"
+//! server my-app port=8080
+//! "#;
+//!
+//! let config: Config = kdl::de::from_str(kdl).unwrap();
+//! assert_eq!(config, Config { server: Server { name: "my-app".into(), port: 8080 }});
+//! ```
 
 use std::borrow::Cow;
 use std::fmt;
@@ -95,7 +189,7 @@ fn str_deserializer(s: &str) -> de::value::StrDeserializer<'_, Error> {
 /// }
 ///
 /// let kdl = r#"
-/// name "my-app"
+/// name my-app
 /// port 8080
 /// "#;
 ///

src/se.rs

@@ -30,6 +30,8 @@
 //! let kdl = kdl::se::to_string(&config).unwrap();
 //! assert_eq!(kdl, "name my-app\nport 8080\n");
 //! ```
+//! You can refer to the [crate::de] module to further customize the
+//! (de)serialization model.
 
 use serde::ser::{self, Serialize};
 use std::fmt;