Merge pull request #495 from zhiburt/patch/work-on-docs

Work on documentation

papergrid/examples/common_grid.rs

@@ -55,15 +55,13 @@ const fn generate_table_config() -> CompactConfig {
         intersection: Some('+'),
     };
 
-    let mut cfg = CompactConfig::new();
-    cfg.set_borders(STYLE);
-    cfg.set_alignment_horizontal(AlignmentHorizontal::Center);
-    cfg.set_padding(Sides::new(
-        Indent::spaced(1),
-        Indent::spaced(1),
-        Indent::spaced(0),
-        Indent::spaced(0),
-    ));
-
-    cfg
+    CompactConfig::new()
+        .set_borders(STYLE)
+        .set_alignment_horizontal(AlignmentHorizontal::Center)
+        .set_padding(Sides::new(
+            Indent::spaced(1),
+            Indent::spaced(1),
+            Indent::spaced(0),
+            Indent::spaced(0),
+        ))
 }

papergrid/examples/common_grid_no_std.rs

@@ -49,17 +49,15 @@ const fn generate_table_config() -> CompactConfig {
         intersection: Some('+'),
     };
 
-    let mut cfg = CompactConfig::new();
-    cfg.set_borders(STYLE);
-    cfg.set_alignment_horizontal(AlignmentHorizontal::Center);
-    cfg.set_padding(Sides::new(
-        Indent::spaced(1),
-        Indent::spaced(1),
-        Indent::spaced(3),
-        Indent::spaced(0),
-    ));
-
-    cfg
+    CompactConfig::new()
+        .set_borders(STYLE)
+        .set_alignment_horizontal(AlignmentHorizontal::Center)
+        .set_padding(Sides::new(
+            Indent::spaced(1),
+            Indent::spaced(1),
+            Indent::spaced(3),
+            Indent::spaced(0),
+        ))
 }
 
 struct ConstDims<'a>(&'a [usize], usize);

papergrid/src/config/compact/mod.rs

@@ -45,8 +45,9 @@ impl CompactConfig {
     }
 
     /// Set grid margin.
-    pub const fn set_margin(&mut self, margin: Sides<Indent>) {
+    pub const fn set_margin(mut self, margin: Sides<Indent>) -> Self {
         self.margin = margin;
+        self
     }
 
     /// Returns a grid margin.
@@ -55,8 +56,9 @@ impl CompactConfig {
     }
 
     /// Set the [`Borders`] value as correct one.
-    pub const fn set_borders(&mut self, borders: Borders<char>) {
+    pub const fn set_borders(mut self, borders: Borders<char>) -> Self {
         self.borders = borders;
+        self
     }
 
     /// Returns a current [`Borders`] structure.
@@ -70,8 +72,9 @@ impl CompactConfig {
     }
 
     /// Set a padding to a given cells.
-    pub const fn set_padding(&mut self, padding: Sides<Indent>) {
+    pub const fn set_padding(mut self, padding: Sides<Indent>) -> Self {
         self.padding = padding;
+        self
     }
 
     /// Get a padding for a given.
@@ -80,8 +83,9 @@ impl CompactConfig {
     }
 
     /// Set a horizontal alignment.
-    pub const fn set_alignment_horizontal(&mut self, alignment: AlignmentHorizontal) {
+    pub const fn set_alignment_horizontal(mut self, alignment: AlignmentHorizontal) -> Self {
         self.halignment = alignment;
+        self
     }
 
     /// Get a alignment horizontal.
@@ -90,13 +94,15 @@ impl CompactConfig {
     }
 
     /// Sets colors of border carcass on the grid.
-    pub const fn set_borders_color(&mut self, borders: Borders<ANSIStr<'static>>) {
+    pub const fn set_borders_color(mut self, borders: Borders<ANSIStr<'static>>) -> Self {
         self.border_colors = borders;
+        self
     }
 
     /// Set colors for a margin.
-    pub const fn set_margin_color(&mut self, color: Sides<ANSIStr<'static>>) {
+    pub const fn set_margin_color(mut self, color: Sides<ANSIStr<'static>>) -> Self {
         self.margin_color = color;
+        self
     }
 
     /// Returns a margin color.
@@ -105,8 +111,9 @@ impl CompactConfig {
     }
 
     /// Set a padding to a given cells.
-    pub const fn set_padding_color(&mut self, color: Sides<ANSIStr<'static>>) {
+    pub const fn set_padding_color(mut self, color: Sides<ANSIStr<'static>>) -> Self {
         self.padding_color = color;
+        self
     }
 
     /// Set a padding to a given cells.

tabled/README.md

@@ -78,4 +78,4 @@ assert_table!(
     "| Hare | Drew DeVault   | 2022 |"
     "'------------------------------'"
 );
-```
+```

tabled/src/derive/mod.rs

@@ -6,26 +6,36 @@ pub mod display;
 ///
 /// The macro available only when `derive` feature in turned on (and it is by default).
 ///
-/// To be able to use the derive each field must implement `std::fmt::Display`.
+/// ```
+/// use tabled::Tabled;
+///
+/// #[derive(Tabled)]
+/// struct SomeType {
+///     field0: &'static str,
+///     field1: String,
+///     field2: usize,
+/// }
+/// ```
+///
+/// To be able to use the derive each field must implement `std::fmt::Display`.\
 /// The following example will cause an error because of that.
 ///
-/// ```rust,compile_fail
+/// ```,compile_fail
 /// use tabled::Tabled;
+///
 /// #[derive(Tabled)]
 /// struct SomeType {
-///     field1: SomeOtherType,
+///     field1: Vec<usize>,
 /// }
-///
-/// struct SomeOtherType;
 /// ```
 ///
 /// Bellow you'll find available options for it.
 ///
-/// ### Override a column name
+/// ## Rename a column name
 ///
 /// You can use a `#[tabled(rename = "")]` attribute to override a column name.
 ///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -37,13 +47,11 @@ pub mod display;
 /// }
 /// ```
 ///
-/// ### Hide a column
+/// ## Hide a column
 ///
 /// You can mark fields as hidden in which case they fill be ignored and not be present on a sheet.
 ///
-/// A similar affect could be achieved by the means of a `Remove`.
-///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -55,11 +63,11 @@ pub mod display;
 /// }
 /// ```
 ///
-/// ### Set column order
+/// ## Set column order
 ///
 /// You can change the order in which they will be displayed in table.
 ///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -72,59 +80,59 @@ pub mod display;
 /// }
 /// ```
 ///
-/// ### Format fields
+/// ## Format fields
 ///
-/// As was said already, using `#[derive(Tabled)]` is possible only when all fields implement a `Display` trait.
-/// However, this may be often not the case for example when a field uses the `Option` type. There's 2 common ways how to solve this:
+/// Using `#[derive(Tabled)]` is possible only when all fields implement a `Display` trait.\
+/// However, this may be not convinient for example when a field uses the `Option` type.\
+/// There's 2 common ways how to solve this:
 ///
 /// - Implement `Tabled` trait manually for a type.
 /// - Wrap `Option` to something like `DisplayedOption<T>(Option<T>)` and implement a Display trait for it.
 ///
-/// Alternatively, you can use the `#[tabled(display = "func")]` attribute for the field to specify a display function.
+/// But, it's not quite convient either.
 ///
-/// ```rust,no_run
-/// use tabled::Tabled;
+/// So alternatively, we provide the next solutions.
 ///
-/// #[derive(Tabled)]
-/// pub struct MyRecord {
-///     pub id: i64,
-///     #[tabled(display = "display_option")]
-///     pub valid: Option<bool>
-/// }
+/// - Use the `#[tabled(display = "func")]` - attribute to set a display function.
+/// - Use the `#[tabled(format = "{}")]` - attribute to format field.
 ///
-/// fn display_option(o: &Option<bool>) -> String {
-///     match o {
-///         Some(s) => format!("is valid thing = {}", s),
-///         None => format!("is not valid"),
-///     }
-/// }
-/// ```
+/// ### `#[tabled(display)]`
+///
+/// A poverfull helper, the set function must have a first argument as a reference to a field.\
+/// It supports custom arguments as well (including `self`).
 ///
-/// It's also possible to change function argument to be `&self`,
-/// using `#[tabled(display("some_function", self))]`
+/// You can set it right on the whole type,\
+/// In which case all fields which are matching a set type will be using the given function.
 ///
-/// ```rust,no_run
+/// We also provide a set of commonly used function for your types.\
+/// You can find them in [`tabled::derive::display`].
+///
+/// ```
 /// use tabled::Tabled;
+/// use tabled::derive::display;
 ///
 /// #[derive(Tabled)]
-/// pub struct MyRecord {
+/// #[tabled(display(i64, "display_i64"))]
+/// pub struct Record {
 ///     pub id: i64,
-///     #[tabled(display("Self::display_valid", self))]
-///     pub valid: Option<bool>
+///     #[tabled(display("display::option", "unvalidated"))]
+///     pub valid: Option<bool>,
+///     #[tabled(display("display_private", self))]
+///     pub private: (),
 /// }
 ///
-/// impl MyRecord {
-///     fn display_valid(_: &Option<bool>, s: &Self) -> String {
-///         match s.valid {
-///             Some(s) => format!("is valid thing = {}", s),
-///             None => format!("is not valid"),
-///         }
-///     }
+/// fn display_private(_: &(), rec: &Record) -> String {
+///     todo!()
+/// }
+///
+/// fn display_i64(val: &i64) -> String {
+///     todo!()
 /// }
 /// ```
 ///
-/// There's also a probably more suitable way for formatting, if your format is constant.
-/// Using `#[tabled(format = "{}")]` and `#[tabled(format("{}"))]` and proving a general formatting string.
+/// ### `#[tabled(format)]`
+///
+/// An analogue to [`format!`], which can be used right on the field.\
 ///
 /// ```
 /// use tabled::Tabled;
@@ -133,17 +141,17 @@ pub mod display;
 /// struct Record {
 ///     #[tabled(skip)]
 ///     id: u8,
-///     #[tabled(format("{}.{}", self.id, self.name))]
+///     #[tabled(format("{}.{}-{}", self.id, self.name, 123))]
 ///     name: String,
 /// }
 /// ```
 ///
-/// ### Format headers
+/// ## Format headers
 ///
-/// Beside `#[tabled(rename = "")]` you can change a format of a column name using
+/// Beside `#[tabled(rename = "")]` you can change a format of a column name using\
 /// `#[tabled(rename_all = "UPPERCASE")]`.
 ///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -157,12 +165,14 @@ pub mod display;
 /// }
 /// ```
 ///
-/// ### Inline
+/// ## Embeding a field
 ///
-/// It's possible to inline internal data if it implements the `Tabled` trait using `#[tabled(inline)]`.
-/// You can also set a prefix which will be used for all inlined elements by `#[tabled(inline("prefix>>"))]`.
+/// You can inline a field or a variant if it implements `Tabled` trait\
+/// using `#[tabled(inline)]`.
+/// You can also set a prefix for inlined elements by given it as a argument\
+/// `#[tabled(inline("::::"))]`.
 ///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -182,7 +192,7 @@ pub mod display;
 ///
 /// And it works for enums as well.
 ///
-/// ```rust,no_run
+/// ```
 /// use tabled::Tabled;
 ///
 /// #[derive(Tabled)]
@@ -205,4 +215,6 @@ pub mod display;
 ///     price: f32,
 /// }
 /// ```
+///
+/// [`tabled::derive::display`]: crate::tabled::derive::display
 pub use tabled_derive::Tabled;