Merge pull request #839 from epage/docs

docs: Distinguish Table/InlineTable

Author: epage

crates/toml_edit/src/array.rs

@@ -5,8 +5,7 @@ use crate::repr::Decor;
 use crate::value::{DEFAULT_LEADING_VALUE_DECOR, DEFAULT_VALUE_DECOR};
 use crate::{Item, RawString, Value};
 
-/// Type representing a TOML array,
-/// payload of the `Value::Array` variant's value
+/// A TOML [`Value`] that contains a sequence of [`Value`]s
 #[derive(Debug, Default, Clone)]
 pub struct Array {
     // `trailing` represents whitespaces, newlines
@@ -20,11 +19,11 @@ pub struct Array {
     pub(crate) values: Vec<Item>,
 }
 
-/// An owned iterator type over `Table`'s key/value pairs.
+/// An owned iterator type over [`Array`]'s [`Value`]s
 pub type ArrayIntoIter = Box<dyn Iterator<Item = Value>>;
-/// An iterator type over `Array`'s values.
+/// An iterator type over [`Array`]'s [`Value`]s
 pub type ArrayIter<'a> = Box<dyn Iterator<Item = &'a Value> + 'a>;
-/// An iterator type over `Array`'s values.
+/// An iterator type over [`Array`]'s [`Value`]s
 pub type ArrayIterMut<'a> = Box<dyn Iterator<Item = &'a mut Value> + 'a>;
 
 /// Constructors

crates/toml_edit/src/array_of_tables.rs

@@ -2,7 +2,7 @@ use std::iter::FromIterator;
 
 use crate::{Array, Item, Table};
 
-/// Type representing a TOML array of tables
+/// A top-level sequence of [`Table`]s, each under their own header
 #[derive(Clone, Debug, Default)]
 pub struct ArrayOfTables {
     // Always Vec<Item::Table>, just `Item` to make `Index` work
@@ -109,11 +109,11 @@ impl ArrayOfTables {
     }
 }
 
-/// An iterator type over `ArrayOfTables`'s values.
+/// An iterator type over [`ArrayOfTables`]'s [`Table`]s
 pub type ArrayOfTablesIter<'a> = Box<dyn Iterator<Item = &'a Table> + 'a>;
-/// An iterator type over `ArrayOfTables`'s values.
+/// An iterator type over [`ArrayOfTables`]'s [`Table`]s
 pub type ArrayOfTablesIterMut<'a> = Box<dyn Iterator<Item = &'a mut Table> + 'a>;
-/// An iterator type over `ArrayOfTables`'s values.
+/// An iterator type over [`ArrayOfTables`]'s [`Table`]s
 pub type ArrayOfTablesIntoIter = Box<dyn Iterator<Item = Table>>;
 
 impl Extend<Table> for ArrayOfTables {

crates/toml_edit/src/document.rs

@@ -3,7 +3,7 @@ use std::str::FromStr;
 use crate::table::Iter;
 use crate::{Item, RawString, Table};
 
-/// Type representing a parsed TOML document
+/// The root TOML [`Table`], containing [`Key`][crate::Key]/[`Value`][crate::Value] pairs and all other logic [`Table`]s
 #[derive(Debug, Clone)]
 pub struct ImDocument<S> {
     pub(crate) root: Item,
@@ -105,7 +105,7 @@ impl<S> std::ops::Deref for ImDocument<S> {
     }
 }
 
-/// Type representing a TOML document
+/// The editable root TOML [`Table`], containing [`Key`][crate::Key]/[`Value`][crate::Value] pairs and all other logic [`Table`]s
 #[derive(Debug, Clone)]
 pub struct DocumentMut {
     pub(crate) root: Item,

crates/toml_edit/src/error.rs

@@ -1,7 +1,7 @@
 use std::error::Error as StdError;
 use std::fmt::{Display, Formatter, Result};
 
-/// Type representing a TOML parse error
+/// A TOML parse error
 #[derive(Debug, Clone, Eq, PartialEq, Hash)]
 pub struct TomlError {
     message: String,

crates/toml_edit/src/inline_table.rs

@@ -5,8 +5,7 @@ use crate::repr::Decor;
 use crate::table::{Iter, IterMut, KeyValuePairs, TableLike};
 use crate::{InternalString, Item, KeyMut, RawString, Table, Value};
 
-/// Type representing a TOML inline table,
-/// payload of the `Value::InlineTable` variant
+/// A TOML [`Value`] that contains a collection of [`Key`]/[`Value`] pairs
 #[derive(Debug, Default, Clone)]
 pub struct InlineTable {
     // `preamble` represents whitespaces in an empty table
@@ -511,11 +510,11 @@ fn decorate_inline_table(table: &mut InlineTable) {
     }
 }
 
-/// An owned iterator type over key/value pairs of an inline table.
+/// An owned iterator type over an [`InlineTable`]'s [`Key`]/[`Value`] pairs
 pub type InlineTableIntoIter = Box<dyn Iterator<Item = (InternalString, Value)>>;
-/// An iterator type over key/value pairs of an inline table.
+/// An iterator type over [`InlineTable`]'s [`Key`]/[`Value`] pairs
 pub type InlineTableIter<'a> = Box<dyn Iterator<Item = (&'a str, &'a Value)> + 'a>;
-/// A mutable iterator type over key/value pairs of an inline table.
+/// A mutable iterator type over [`InlineTable`]'s [`Key`]/[`Value`] pairs
 pub type InlineTableIterMut<'a> = Box<dyn Iterator<Item = (KeyMut<'a>, &'a mut Value)> + 'a>;
 
 impl TableLike for InlineTable {
@@ -613,7 +612,7 @@ impl TableLike for InlineTable {
 // `{ key1 = value1, ... }`
 pub(crate) const DEFAULT_INLINE_KEY_DECOR: (&str, &str) = (" ", " ");
 
-/// A view into a single location in a map, which may be vacant or occupied.
+/// A view into a single location in an [`InlineTable`], which may be vacant or occupied.
 pub enum InlineEntry<'a> {
     /// An occupied Entry.
     Occupied(InlineOccupiedEntry<'a>),
@@ -659,7 +658,7 @@ impl<'a> InlineEntry<'a> {
     }
 }
 
-/// A view into a single occupied location in a `IndexMap`.
+/// A view into a single occupied location in an [`InlineTable`].
 pub struct InlineOccupiedEntry<'a> {
     entry: indexmap::map::OccupiedEntry<'a, Key, Item>,
 }
@@ -714,7 +713,7 @@ impl<'a> InlineOccupiedEntry<'a> {
     }
 }
 
-/// A view into a single empty location in a `IndexMap`.
+/// A view into a single empty location in an [`InlineTable`].
 pub struct InlineVacantEntry<'a> {
     entry: indexmap::map::VacantEntry<'a, Key, Item>,
 }

crates/toml_edit/src/item.rs

@@ -72,49 +72,61 @@ impl Item {
         index.index_mut(self)
     }
 
-    /// Casts `self` to value.
+    /// Casts `self` to [`Value`]
     pub fn as_value(&self) -> Option<&Value> {
         match *self {
             Item::Value(ref v) => Some(v),
             _ => None,
         }
     }
-    /// Casts `self` to table.
+    /// Casts `self` to [`Table`]
+    ///
+    /// <div class="warning">
+    ///
+    /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::as_table_like`]
+    ///
+    /// </div>
     pub fn as_table(&self) -> Option<&Table> {
         match *self {
             Item::Table(ref t) => Some(t),
             _ => None,
         }
     }
-    /// Casts `self` to array of tables.
+    /// Casts `self` to [`ArrayOfTables`]
     pub fn as_array_of_tables(&self) -> Option<&ArrayOfTables> {
         match *self {
             Item::ArrayOfTables(ref a) => Some(a),
             _ => None,
         }
     }
-    /// Casts `self` to mutable value.
+    /// Casts `self` to mutable [`Value`].
     pub fn as_value_mut(&mut self) -> Option<&mut Value> {
         match *self {
             Item::Value(ref mut v) => Some(v),
             _ => None,
         }
     }
-    /// Casts `self` to mutable table.
+    /// Casts `self` to mutable [`Table`]
+    ///
+    /// <div class="warning">
+    ///
+    /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::as_table_like_mut`]
+    ///
+    /// </div>
     pub fn as_table_mut(&mut self) -> Option<&mut Table> {
         match *self {
             Item::Table(ref mut t) => Some(t),
             _ => None,
         }
     }
-    /// Casts `self` to mutable array of tables.
+    /// Casts `self` to mutable [`ArrayOfTables`]
     pub fn as_array_of_tables_mut(&mut self) -> Option<&mut ArrayOfTables> {
         match *self {
             Item::ArrayOfTables(ref mut a) => Some(a),
             _ => None,
         }
     }
-    /// Casts `self` to value.
+    /// Casts `self` to [`Value`]
     pub fn into_value(self) -> Result<Value, Self> {
         match self {
             Item::None => Err(self),
@@ -135,15 +147,21 @@ impl Item {
         let other = other.into_value().map(Item::Value).unwrap_or(Item::None);
         *self = other;
     }
-    /// Casts `self` to table.
+    /// Casts `self` to [`Table`]
+    ///
+    /// <div class="warning">
+    ///
+    /// This does not include [`InlineTable`]s
+    ///
+    /// </div>
     pub fn into_table(self) -> Result<Table, Self> {
         match self {
             Item::Table(t) => Ok(t),
             Item::Value(Value::InlineTable(t)) => Ok(t.into_table()),
             _ => Err(self),
         }
     }
-    /// Casts `self` to array of tables.
+    /// Casts `self` to [`ArrayOfTables`]
     pub fn into_array_of_tables(self) -> Result<ArrayOfTables, Self> {
         match self {
             Item::ArrayOfTables(a) => Ok(a),
@@ -177,15 +195,21 @@ impl Item {
         };
         *self = other;
     }
-    /// Returns true if `self` is a value.
+    /// Returns true if `self` is a [`Value`]
     pub fn is_value(&self) -> bool {
         self.as_value().is_some()
     }
-    /// Returns true if `self` is a table.
+    /// Returns true if `self` is a [`Table`]
+    ///
+    /// <div class="warning">
+    ///
+    /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::is_table_like`]
+    ///
+    /// </div>
     pub fn is_table(&self) -> bool {
         self.as_table().is_some()
     }
-    /// Returns true if `self` is an array of tables.
+    /// Returns true if `self` is an [`ArrayOfTables`]
     pub fn is_array_of_tables(&self) -> bool {
         self.as_array_of_tables().is_some()
     }

crates/toml_edit/src/key.rs

@@ -4,7 +4,8 @@ use std::str::FromStr;
 use crate::repr::{Decor, Repr};
 use crate::InternalString;
 
-/// Key as part of a Key/Value Pair or a table header.
+/// For Key/[`Value`][crate::Value] pairs under a [`Table`][crate::Table] header or inside an
+/// [`InlineTable`][crate::InlineTable]
 ///
 /// # Examples
 ///
@@ -333,7 +334,7 @@ impl From<Key> for InternalString {
     }
 }
 
-/// A mutable reference to a `Key`'s formatting
+/// A mutable reference to a [`Key`]'s formatting
 #[derive(Debug, Eq, PartialEq, PartialOrd, Ord, Hash)]
 pub struct KeyMut<'k> {
     key: &'k mut Key,

crates/toml_edit/src/repr.rs

@@ -2,8 +2,9 @@ use std::borrow::Cow;
 
 use crate::RawString;
 
-/// A value together with its `to_string` representation,
-/// including surrounding it whitespaces and comments.
+/// A scalar TOML [`Value`][crate::Value]'s logical value and its representation in a `&str`
+///
+/// This includes the surrounding whitespace and comments.
 #[derive(Eq, PartialEq, Clone, Hash)]
 pub struct Formatted<T> {
     value: T,
@@ -134,7 +135,7 @@ mod inner {
     impl ValueRepr for toml_datetime::Datetime {}
 }
 
-/// TOML-encoded value
+/// A TOML [`Value`][crate::Value] encoded as a `&str`
 #[derive(Eq, PartialEq, Clone, Hash)]
 pub struct Repr {
     raw_value: RawString,

crates/toml_edit/src/table.rs

@@ -7,7 +7,8 @@ use crate::repr::Decor;
 use crate::value::DEFAULT_VALUE_DECOR;
 use crate::{InlineTable, InternalString, Item, KeyMut, Value};
 
-/// Type representing a TOML non-inline table
+/// A TOML table, a top-level collection of key/[`Value`] pairs under a header and logical
+/// sub-tables
 #[derive(Clone, Debug, Default)]
 pub struct Table {
     // Comments/spaces before and after the header
@@ -524,11 +525,11 @@ pub(crate) const DEFAULT_KEY_DECOR: (&str, &str) = ("", " ");
 pub(crate) const DEFAULT_TABLE_DECOR: (&str, &str) = ("\n", "");
 pub(crate) const DEFAULT_KEY_PATH_DECOR: (&str, &str) = ("", "");
 
-/// An owned iterator type over `Table`'s key/value pairs.
+/// An owned iterator type over [`Table`]'s [`Key`]/[`Item`] pairs
 pub type IntoIter = Box<dyn Iterator<Item = (InternalString, Item)>>;
-/// An iterator type over `Table`'s key/value pairs.
+/// An iterator type over [`Table`]'s [`Key`]/[`Item`] pairs
 pub type Iter<'a> = Box<dyn Iterator<Item = (&'a str, &'a Item)> + 'a>;
-/// A mutable iterator type over `Table`'s key/value pairs.
+/// A mutable iterator type over [`Table`]'s [`Key`]/[`Item`] pairs
 pub type IterMut<'a> = Box<dyn Iterator<Item = (KeyMut<'a>, &'a mut Item)> + 'a>;
 
 /// This trait represents either a `Table`, or an `InlineTable`.
@@ -664,7 +665,7 @@ impl TableLike for Table {
     }
 }
 
-/// A view into a single location in a map, which may be vacant or occupied.
+/// A view into a single location in a [`Table`], which may be vacant or occupied.
 pub enum Entry<'a> {
     /// An occupied Entry.
     Occupied(OccupiedEntry<'a>),
@@ -710,7 +711,7 @@ impl<'a> Entry<'a> {
     }
 }
 
-/// A view into a single occupied location in a `IndexMap`.
+/// A view into a single occupied location in a [`Table`].
 pub struct OccupiedEntry<'a> {
     pub(crate) entry: indexmap::map::OccupiedEntry<'a, Key, Item>,
 }
@@ -764,7 +765,7 @@ impl<'a> OccupiedEntry<'a> {
     }
 }
 
-/// A view into a single empty location in a `IndexMap`.
+/// A view into a single empty location in a [`Table`].
 pub struct VacantEntry<'a> {
     pub(crate) entry: indexmap::map::VacantEntry<'a, Key, Item>,
 }

crates/toml_edit/src/value.rs

@@ -7,7 +7,8 @@ use crate::key::Key;
 use crate::repr::{Decor, Formatted};
 use crate::{Array, InlineTable, InternalString, RawString};
 
-/// Representation of a TOML Value (as part of a Key/Value Pair).
+/// For [`Key`]/Value pairs under a [`Table`][crate::Table] header or inside another
+/// Value
 #[derive(Debug, Clone)]
 pub enum Value {
     /// A string value.