Add documentation

charming/Cargo.toml

@@ -12,14 +12,14 @@ license = "MIT/Apache-2.0"
 readme = "../README.md"
 
 [dependencies]
-deno_core = { version = "0.195.0", optional = true }
-gdk-pixbuf = { version = "0.17.10", optional = true }
-handlebars = "4.3.7"
-serde = { version = "1.0.164", features = ["derive"] }
-serde-wasm-bindgen = {version = "0.5.0", optional = true }
-serde_json = "1.0.99"
-serde_v8 = { version = "0.106.0", optional = true }
-wasm-bindgen = { version = "0.2.87", optional = true }
+deno_core = { version = "0.195", optional = true }
+gdk-pixbuf = { version = "0.17", optional = true }
+handlebars = "4.3"
+serde = { version = "1.0", features = ["derive"] }
+serde-wasm-bindgen = {version = "0.5", optional = true }
+serde_json = "1.0"
+serde_v8 = { version = "0.106", optional = true }
+wasm-bindgen = { version = "0.2", optional = true }
 
 [dependencies.web-sys]
 version = "0.3.64"

charming/src/datatype/dataframe.rs

@@ -1,5 +1,51 @@
 use super::DataPoint;
 
+/// [`DataFrame`] is the basic data representation in Echarts.
+///
+/// ## DataFrame
+///
+/// Basically, data in Echarts is represented by a nested array. like the
+/// following example, where each column is named as a "dimension".
+///
+/// data: [
+///     // dimX   dimY   other dimensions ...
+///     [  3.4,    4.5,   15,   43],
+///     [  4.2,    2.3,   20,   91],
+///     [  10.8,   9.5,   30,   18],
+///     [  7.2,    8.8,   18,   57]
+/// ]
+///
+/// We can use the [`df`] macro to construct a DataFrame. For example, to
+/// construct the above DataFrame, you can write code like this:
+///
+/// ```rust
+/// use charming::datatype::DataFrame;
+/// use charming::df;
+///
+/// let data: DataFrame = df![
+///    [3.4, 4.5, 15, 43],
+///    [4.2, 2.3, 20, 91],
+///    [10.8, 9.5, 30, 18],
+///    [7.2, 8.8, 18, 57]
+/// ];
+/// ```
+///
+/// Especially, when there is only one dimension in each row, data can be
+/// simply represented by a plain array, like the following example:
+///
+/// data: [1, 1, 2, 3, 5, 7, 13]
+///
+/// We can use the second form of the [`df`] macro to construct the above
+/// simplified DataFrame. For example, to construct the above DataFrame, you
+/// can write code like this:
+///
+/// ```rust
+/// use charming::datatype::DataFrame;
+/// use charming::df;
+///
+/// let data: DataFrame = df![1, 1, 2, 3, 5, 7, 13];
+/// ```
+///
 pub type DataFrame = Vec<DataPoint>;
 
 #[macro_export]