be more strict about missing / invalid documentation

[amtoine]

i think adding

#![warn(
    clippy::missing_docs_in_private_items,
    missing_docs,
    rustdoc::broken_intra_doc_links,
    rustdoc::missing_crate_level_docs,
    rustdoc::missing_doc_code_examples,
    rustdoc::private_intra_doc_links
)]

to the header of lib.rs would be a good idea

doc that could be added

diff --git a/src/app.rs b/src/app.rs
index 27658f9..fda9726 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -26,7 +26,7 @@ pub(super) enum Mode {
     Insert,
     /// the PEEKING mode lets the user *peek* data out of the application, to be reused later
     Peeking,
-    /// TODO: documentation
+    /// the BOTTOM mode tells when the user hit the bottom of the data, i.e to the far right
     Bottom,
 }
 
@@ -85,12 +85,12 @@ impl State {
         state
     }
 
-    /// TODO: documentation
+    /// teel if the state is currently in the BOTTOM mode
     pub(super) fn is_at_bottom(&self) -> bool {
         matches!(self.mode, Mode::Bottom)
     }
 
-    /// TODO: documentation
+    /// set the mode to BOTTOM
     pub(super) fn hit_bottom(&mut self) {
         self.mode = Mode::Bottom;
     }
diff --git a/src/tui.rs b/src/tui.rs
index 082b9ec..95f4efb 100644
--- a/src/tui.rs
+++ b/src/tui.rs
@@ -59,7 +59,8 @@ impl DataRowRepr {
 
 /// compute the preview representation of a list
 ///
-/// > see the tests for detailed examples
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_list(vals: &[Value]) -> DataRowRepr {
     let data = match vals.len() {
         0 => "[]".into(),
@@ -76,7 +77,8 @@ fn repr_list(vals: &[Value]) -> DataRowRepr {
 
 /// compute the preview representation of a record
 ///
-/// > see the tests for detailed examples
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_record(cols: &[String]) -> DataRowRepr {
     let data = match cols.len() {
         0 => "{}".into(),
@@ -91,9 +93,11 @@ fn repr_record(cols: &[String]) -> DataRowRepr {
     }
 }
 
-/// TODO: documentation
+/// a way to represent special strings, i.e. regular strings but with more meaning
 enum SpecialString {
+    // a web URL with some protocol
     Url,
+    // a path on a filesystem
     Path,
 }
 
@@ -107,8 +111,12 @@ impl std::fmt::Display for SpecialString {
     }
 }
 
-/// TODO: documentation
 impl SpecialString {
+    /// parse a regular string and tell if it's a special one
+    ///
+    /// [`parse`] will return `Some(Self::Path)` when the input might be a path,
+    /// `Some(Self::Url)` when it is a valid URL and finally `None` if it's just
+    /// a regular string.
     fn parse(input: &str) -> Option<Self> {
         if let Ok(url) = url::Url::parse(input) {
             if url.scheme() == "file" {
@@ -126,7 +134,8 @@ impl SpecialString {
 
 /// compute the preview representation of a simple value
 ///
-/// > see the tests for detailed examples
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_simple_value(value: &Value) -> DataRowRepr {
     let shape = match value {
         Value::String { val, .. } => match SpecialString::parse(val) {
@@ -145,7 +154,8 @@ fn repr_simple_value(value: &Value) -> DataRowRepr {
 
 /// compute the preview representation of a value
 ///
-/// > see the tests for detailed examples
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_value(value: &Value) -> DataRowRepr {
     match value {
         Value::List { vals, .. } => repr_list(vals),
@@ -156,7 +166,8 @@ fn repr_value(value: &Value) -> DataRowRepr {
 
 /// compute the row / item representation of a complete Nushell Value
 ///
-/// > see the tests for detailed examples
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_data(data: &Value, cell_path: &[PathMember]) -> Vec<DataRowRepr> {
     match data.clone().follow_cell_path(cell_path, false) {
         Err(_) => panic!("unexpected error when following cell path during rendering"),
@@ -193,7 +204,23 @@ fn repr_data(data: &Value, cell_path: &[PathMember]) -> Vec<DataRowRepr> {
     }
 }
 
-/// TODO: documentation
+/// tell whether or not a cell in a value is a valid Nushell table
+///
+/// this function will traverse `value` to the end of the `cell_path` and tell
+/// whether or not this value is a real table.
+///
+/// # return values
+/// - `Some(false)` if the cell is not a table
+/// - `Some(true)` if it is
+/// - `None` if following the `cell_path` in the top-level `value` gave an erorr,
+/// i.e. the cell_path is probably incorrect.
+///
+/// # what is a table
+/// here, a table is defined as follows
+/// - it is a list
+/// - each item in the list is a record
+/// - all records have the same columns
+/// - all records have the same types for each of their fields
 fn is_table(value: &Value, cell_path: &[PathMember]) -> Option<bool> {
     match value.clone().follow_cell_path(cell_path, false) {
         Ok(Value::List { vals, .. }) => {
@@ -216,7 +243,14 @@ fn is_table(value: &Value, cell_path: &[PathMember]) -> Option<bool> {
 
 /// compute the representation of a complete Nushell table
 ///
-/// > see the tests for detailed examples
+/// this function will assume the input `table` is a table, no check or error
+/// handling will be performed.
+///
+/// to know what a *table* is, please refer to [`is_table`].
+/// here, `table` is the list of all the records in the table.
+///
+/// # examples
+/// see the [tests] for detailed examples
 fn repr_table(table: &[Value]) -> (Vec<String>, Vec<String>, Vec<Vec<String>>) {
     let shapes = table[0]
         .columns()