From b8a207cbd9b73afd6b91e8a0c43587526221879b Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 5 Mar 2025 13:05:11 -0600 Subject: [PATCH 1/2] docs: Clarify summary for types --- crates/toml_edit/src/array.rs | 9 ++++----- crates/toml_edit/src/array_of_tables.rs | 8 ++++---- crates/toml_edit/src/document.rs | 4 ++-- crates/toml_edit/src/error.rs | 2 +- crates/toml_edit/src/inline_table.rs | 15 +++++++-------- crates/toml_edit/src/key.rs | 5 +++-- crates/toml_edit/src/repr.rs | 7 ++++--- crates/toml_edit/src/table.rs | 15 ++++++++------- crates/toml_edit/src/value.rs | 3 ++- 9 files changed, 35 insertions(+), 33 deletions(-) diff --git a/crates/toml_edit/src/array.rs b/crates/toml_edit/src/array.rs index 3f1920e7..bcd2b961 100644 --- a/crates/toml_edit/src/array.rs +++ b/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, } -/// An owned iterator type over `Table`'s key/value pairs. +/// An owned iterator type over [`Array`]'s [`Value`]s pub type ArrayIntoIter = Box>; -/// An iterator type over `Array`'s values. +/// An iterator type over [`Array`]'s [`Value`]s pub type ArrayIter<'a> = Box + 'a>; -/// An iterator type over `Array`'s values. +/// An iterator type over [`Array`]'s [`Value`]s pub type ArrayIterMut<'a> = Box + 'a>; /// Constructors diff --git a/crates/toml_edit/src/array_of_tables.rs b/crates/toml_edit/src/array_of_tables.rs index b562f899..22f3fb25 100644 --- a/crates/toml_edit/src/array_of_tables.rs +++ b/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, 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 + 'a>; -/// An iterator type over `ArrayOfTables`'s values. +/// An iterator type over [`ArrayOfTables`]'s [`Table`]s pub type ArrayOfTablesIterMut<'a> = Box + 'a>; -/// An iterator type over `ArrayOfTables`'s values. +/// An iterator type over [`ArrayOfTables`]'s [`Table`]s pub type ArrayOfTablesIntoIter = Box>; impl Extend for ArrayOfTables { diff --git a/crates/toml_edit/src/document.rs b/crates/toml_edit/src/document.rs index 40edf76d..e7d00916 100644 --- a/crates/toml_edit/src/document.rs +++ b/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 { pub(crate) root: Item, @@ -105,7 +105,7 @@ impl std::ops::Deref for ImDocument { } } -/// 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, diff --git a/crates/toml_edit/src/error.rs b/crates/toml_edit/src/error.rs index 409e38bf..15bbb51c 100644 --- a/crates/toml_edit/src/error.rs +++ b/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, diff --git a/crates/toml_edit/src/inline_table.rs b/crates/toml_edit/src/inline_table.rs index 9b8e9c42..829b5741 100644 --- a/crates/toml_edit/src/inline_table.rs +++ b/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>; -/// 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 + '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, &'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>, } diff --git a/crates/toml_edit/src/key.rs b/crates/toml_edit/src/key.rs index a9293d2a..a5ad40aa 100644 --- a/crates/toml_edit/src/key.rs +++ b/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 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, diff --git a/crates/toml_edit/src/repr.rs b/crates/toml_edit/src/repr.rs index cae7cac3..76a1d25c 100644 --- a/crates/toml_edit/src/repr.rs +++ b/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 { 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, diff --git a/crates/toml_edit/src/table.rs b/crates/toml_edit/src/table.rs index 1ae02310..20bd2871 100644 --- a/crates/toml_edit/src/table.rs +++ b/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>; -/// An iterator type over `Table`'s key/value pairs. +/// An iterator type over [`Table`]'s [`Key`]/[`Item`] pairs pub type Iter<'a> = Box + '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, &'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>, } diff --git a/crates/toml_edit/src/value.rs b/crates/toml_edit/src/value.rs index 02ee5e34..65845185 100644 --- a/crates/toml_edit/src/value.rs +++ b/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. From 3ac4d9caac3ec23b79ae813ae8a0f359fac9afb9 Mon Sep 17 00:00:00 2001 From: Ed Page Date: Wed, 5 Mar 2025 13:10:01 -0600 Subject: [PATCH 2/2] docs: Distinguish Table/InlineTable on Item --- crates/toml_edit/src/item.rs | 48 +++++++++++++++++++++++++++--------- 1 file changed, 36 insertions(+), 12 deletions(-) diff --git a/crates/toml_edit/src/item.rs b/crates/toml_edit/src/item.rs index 5b5b64fe..d1c7b293 100644 --- a/crates/toml_edit/src/item.rs +++ b/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`] + /// + ///
+ /// + /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::as_table_like`] + /// + ///
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`] + /// + ///
+ /// + /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::as_table_like_mut`] + /// + ///
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 { match self { Item::None => Err(self), @@ -135,7 +147,13 @@ impl Item { let other = other.into_value().map(Item::Value).unwrap_or(Item::None); *self = other; } - /// Casts `self` to table. + /// Casts `self` to [`Table`] + /// + ///
+ /// + /// This does not include [`InlineTable`]s + /// + ///
pub fn into_table(self) -> Result { match self { Item::Table(t) => Ok(t), @@ -143,7 +161,7 @@ impl Item { _ => Err(self), } } - /// Casts `self` to array of tables. + /// Casts `self` to [`ArrayOfTables`] pub fn into_array_of_tables(self) -> Result { 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`] + /// + ///
+ /// + /// To operate on both [`Table`]s and [`InlineTable`]s, see [`Item::is_table_like`] + /// + ///
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() }