docs(elements): some doc comment for struct and fields

orgize/src/elements/block.rs

@@ -4,11 +4,14 @@ use nom::{bytes::complete::tag_no_case, character::complete::alpha1, sequence::p
 
 use crate::parsers::{line, take_lines_while};
 
+/// Special Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct SpecialBlock<'a> {
+    /// Optional block parameters
     pub parameters: Option<Cow<'a, str>>,
+    /// Block name
     pub name: Cow<'a, str>,
 }
 
@@ -21,10 +24,12 @@ impl SpecialBlock<'_> {
     }
 }
 
+/// Quote Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct QuoteBlock<'a> {
+    /// Optional block parameters
     pub parameters: Option<Cow<'a, str>>,
 }
 
@@ -36,10 +41,12 @@ impl QuoteBlock<'_> {
     }
 }
 
+/// Center Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct CenterBlock<'a> {
+    /// Optional block parameters
     pub parameters: Option<Cow<'a, str>>,
 }
 
@@ -51,10 +58,12 @@ impl CenterBlock<'_> {
     }
 }
 
+/// Verse Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct VerseBlock<'a> {
+    /// Optional block parameters
     pub parameters: Option<Cow<'a, str>>,
 }
 
@@ -66,11 +75,13 @@ impl VerseBlock<'_> {
     }
 }
 
+/// Comment Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct CommentBlock<'a> {
     pub data: Option<Cow<'a, str>>,
+    /// Comment, without block's boundaries
     pub contents: Cow<'a, str>,
 }
 
@@ -83,11 +94,13 @@ impl CommentBlock<'_> {
     }
 }
 
+/// Example Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct ExampleBlock<'a> {
     pub data: Option<Cow<'a, str>>,
+    ///  Block contents
     pub contents: Cow<'a, str>,
 }
 
@@ -100,11 +113,13 @@ impl ExampleBlock<'_> {
     }
 }
 
+/// Export Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct ExportBlock<'a> {
     pub data: Cow<'a, str>,
+    ///  Block contents
     pub contents: Cow<'a, str>,
 }
 
@@ -117,11 +132,14 @@ impl ExportBlock<'_> {
     }
 }
 
+/// Src Block Element
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 pub struct SourceBlock<'a> {
+    ///  Block contents
     pub contents: Cow<'a, str>,
+    /// Language of the code in the block
     pub language: Cow<'a, str>,
     pub arguments: Cow<'a, str>,
 }
@@ -134,6 +152,12 @@ impl SourceBlock<'_> {
             contents: self.contents.into_owned().into(),
         }
     }
+
+    // TODO: fn number_lines() -> Some(New) | Some(Continued) | None {  }
+    // TODO: fn preserve_indent() -> bool {  }
+    // TODO: fn use_labels() -> bool {  }
+    // TODO: fn label_fmt() -> Option<String> {  }
+    // TODO: fn retain_labels() -> bool {  }
 }
 
 pub(crate) fn parse_block_element(input: &str) -> IResult<&str, (&str, Option<&str>, &str)> {

orgize/src/elements/clock.rs

@@ -11,26 +11,28 @@ use nom::{
 use crate::elements::{Datetime, Timestamp};
 use crate::parsers::eol;
 
-/// clock elements
+/// Clock Element
-///
-/// there are two types of clock: *closed* clock and *running* clock.
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[cfg_attr(feature = "ser", serde(untagged))]
 #[derive(Debug)]
 pub enum Clock<'a> {
-    /// closed Clock
+    /// Closed Clock
     Closed {
+        /// Time start
         start: Datetime<'a>,
+        /// Time end
         end: Datetime<'a>,
         #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
         repeater: Option<Cow<'a, str>>,
         #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
         delay: Option<Cow<'a, str>>,
+        /// Clock duration
         duration: Cow<'a, str>,
     },
-    /// running Clock
+    /// Running Clock
     Running {
+        /// Time start
         start: Datetime<'a>,
         #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
         repeater: Option<Cow<'a, str>>,
@@ -117,7 +119,7 @@ impl Clock<'_> {
         }
     }
 
-    /// returns `true` if the clock is running
+    /// Returns `true` if the clock is running.
     pub fn is_running(&self) -> bool {
         match self {
             Clock::Closed { .. } => false,
@@ -125,7 +127,7 @@ impl Clock<'_> {
         }
     }
 
-    /// returns `true` if the clock is closed
+    /// Returns `true` if the clock is closed.
     pub fn is_closed(&self) -> bool {
         match self {
             Clock::Closed { .. } => true,
@@ -133,7 +135,7 @@ impl Clock<'_> {
         }
     }
 
-    /// returns `Some` if the clock is closed, `None` if running
+    /// Returns clock duration, or `None` if it's running.
     pub fn duration(&self) -> Option<&str> {
         match self {
             Clock::Closed { duration, .. } => Some(duration),
@@ -141,7 +143,7 @@ impl Clock<'_> {
         }
     }
 
-    /// constructs a new timestamp object from the clock
+    /// Constructs a timestamp from the clock.
     pub fn value(&self) -> Timestamp<'_> {
         match &*self {
             Clock::Closed {

orgize/src/elements/cookie.rs

@@ -9,10 +9,12 @@ use nom::{
     IResult,
 };
 
+/// Statistics Cookie Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Cookie<'a> {
+    /// Full cookie value
     pub value: Cow<'a, str>,
 }
 

orgize/src/elements/drawer.rs

@@ -8,10 +8,12 @@ use nom::{
 
 use crate::parsers::{eol, line, take_lines_while};
 
+/// Drawer Element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Drawer<'a> {
+    /// Drawer name
     pub name: Cow<'a, str>,
 }
 

orgize/src/elements/dyn_block.rs

@@ -8,11 +8,14 @@ use nom::{
 
 use crate::parsers::{line, take_lines_while};
 
+/// Dynamic Block Element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct DynBlock<'a> {
+    /// Block name
     pub block_name: Cow<'a, str>,
+    /// Block argument
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub arguments: Option<Cow<'a, str>>,
 }

orgize/src/elements/fn_def.rs

@@ -8,10 +8,12 @@ use nom::{
 
 use crate::parsers::line;
 
+/// Footnote Definition Element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct FnDef<'a> {
+    /// Footnote label, used for refrence
     pub label: Cow<'a, str>,
 }
 

orgize/src/elements/fn_ref.rs

@@ -10,10 +10,12 @@ use nom::{
     Err, IResult,
 };
 
+/// Footnote Reference Element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct FnRef<'a> {
+    /// Footnote label
     pub label: Cow<'a, str>,
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub definition: Option<Cow<'a, str>>,

orgize/src/elements/inline_call.rs

@@ -7,14 +7,19 @@ use nom::{
     IResult,
 };
 
+/// Inline Babel Call Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct InlineCall<'a> {
+    /// Called code block name
     pub name: Cow<'a, str>,
+    /// Header arguments applied to the code block
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub inside_header: Option<Cow<'a, str>>,
+    /// Arugment passed to the code block
     pub arguments: Cow<'a, str>,
+    /// Header arguments applied to the calling instance
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub end_header: Option<Cow<'a, str>>,
 }

orgize/src/elements/inline_src.rs

@@ -7,13 +7,17 @@ use nom::{
     IResult,
 };
 
+/// Inline Src Block Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct InlineSrc<'a> {
+    /// Language of the code
     pub lang: Cow<'a, str>,
+    /// Optional header arguments
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub options: Option<Cow<'a, str>>,
+    /// Source code
     pub body: Cow<'a, str>,
 }
 

orgize/src/elements/keyword.rs

@@ -9,13 +9,16 @@ use nom::{
 
 use crate::parsers::line;
 
+/// Keyword Elemenet
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Keyword<'a> {
+    /// Keyword name
     pub key: Cow<'a, str>,
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub optional: Option<Cow<'a, str>>,
+    /// Keyword value
     pub value: Cow<'a, str>,
 }
 
@@ -29,6 +32,7 @@ impl Keyword<'_> {
     }
 }
 
+/// Babel Call Elemenet
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]

orgize/src/elements/link.rs

@@ -7,10 +7,12 @@ use nom::{
     IResult,
 };
 
+/// Link Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Link<'a> {
+    /// Link destination
     pub path: Cow<'a, str>,
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub desc: Option<Cow<'a, str>>,

orgize/src/elements/list.rs

@@ -3,6 +3,7 @@ use std::iter::once;
 
 use memchr::memchr_iter;
 
+/// Plain List Element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
@@ -63,10 +64,12 @@ impl List {
     }
 }
 
+/// List Item Elemenet
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct ListItem<'a> {
+    /// List item bullet
     pub bullet: Cow<'a, str>,
 }
 

orgize/src/elements/macros.rs

@@ -7,11 +7,14 @@ use nom::{
     IResult,
 };
 
+/// Macro Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Macros<'a> {
+    /// Macro name
     pub name: Cow<'a, str>,
+    /// Arguments passed to the macro
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub arguments: Option<Cow<'a, str>>,
 }

orgize/src/elements/mod.rs

@@ -55,7 +55,7 @@ pub use self::{
 
 use std::borrow::Cow;
 
-/// Org-mode element enum
+/// Orgize Element Enum
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]

orgize/src/elements/planning.rs

@@ -2,18 +2,18 @@ use memchr::memchr;
 
 use crate::elements::Timestamp;
 
-/// palnning elements
+/// Palnning element
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Planning<'a> {
-    /// the date when the task should be done
+    /// Timestamp associated to deadline keyword
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub deadline: Option<Timestamp<'a>>,
-    /// the date when you should start working on the task
+    /// Timestamp associated to scheduled keyword
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub scheduled: Option<Timestamp<'a>>,
-    /// the date when the task is closed
+    /// Timestamp associated to closed keyword
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub closed: Option<Timestamp<'a>>,
 }

orgize/src/elements/snippet.rs

@@ -1,16 +1,19 @@
 use std::borrow::Cow;
 
 use nom::{
-    bytes::complete::{tag, take_until, take_while1},
+    bytes::complete::{tag, take, take_until, take_while1},
     sequence::{delimited, separated_pair},
     IResult,
 };
 
+/// Export Snippet Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Snippet<'a> {
+    /// Back-end name
     pub name: Cow<'a, str>,
+    /// Export code
     pub value: Cow<'a, str>,
 }
 
@@ -24,7 +27,7 @@ impl Snippet<'_> {
                 tag(":"),
                 take_until("@@"),
             ),
-            tag("@@"),
+            take(2usize),
         )(input)?;
 
         Ok((

orgize/src/elements/table.rs

@@ -7,13 +7,16 @@ use nom::{
 
 use crate::parsers::{line, take_lines_while};
 
+/// Table Elemenet
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[cfg_attr(feature = "ser", serde(tag = "table_type"))]
 pub enum Table<'a> {
+    /// "org" type table
     #[cfg_attr(feature = "ser", serde(rename = "org"))]
     Org { tblfm: Option<Cow<'a, str>> },
+    /// "table.el" type table
     #[cfg_attr(feature = "ser", serde(rename = "table.el"))]
     TableEl { value: Cow<'a, str> },
 }
@@ -31,13 +34,12 @@ impl Table<'_> {
     }
 }
 
+/// Table Row Elemenet
 #[derive(Debug)]
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
-#[cfg_attr(
+#[cfg_attr(feature = "ser", serde(tag = "table_row_type"))]
-    feature = "ser",
+#[cfg_attr(feature = "ser", serde(rename_all = "kebab-case"))]
-    serde(tag = "table_row_type", rename_all = "kebab-case")
-)]
 pub enum TableRow {
     Standard,
     Rule,

orgize/src/elements/target.rs

@@ -7,10 +7,12 @@ use nom::{
     IResult,
 };
 
+/// Target Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Target<'a> {
+    /// Target ID
     pub target: Cow<'a, str>,
 }
 

orgize/src/elements/timestamp.rs

@@ -8,14 +8,7 @@ use nom::{
     IResult,
 };
 
-/// Datetime
+/// Orgize Datetime Struct
-///
-/// # Syntax
-///
-/// ```text
-/// YYYY-MM-DD DAYNAME
-/// ```
-///
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug, Clone)]
@@ -101,12 +94,11 @@ mod chrono {
     }
 }
 
+/// Timestamp Object
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
-#[cfg_attr(
+#[cfg_attr(feature = "ser", serde(rename_all = "kebab-case"))]
-    feature = "ser",
+#[cfg_attr(feature = "ser", serde(tag = "timestamp_type"))]
-    serde(tag = "timestamp_type", rename_all = "kebab-case")
-)]
 #[derive(Debug)]
 pub enum Timestamp<'a> {
     Active {

orgize/src/elements/title.rs

@@ -19,24 +19,28 @@ use crate::config::ParseConfig;
 use crate::elements::{Drawer, Planning, Timestamp};
 use crate::parsers::{line, skip_empty_lines, take_one_word};
 
+/// Title Elemenet
 #[cfg_attr(test, derive(PartialEq))]
 #[cfg_attr(feature = "ser", derive(serde::Serialize))]
 #[derive(Debug)]
 pub struct Title<'a> {
-    /// headline level, number of stars
+    /// Headline level, number of stars
     pub level: usize,
-    /// priority cookie
+    /// Headline priority cookie
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub priority: Option<char>,
-    /// headline tags, including the sparated colons
+    /// Headline title tags, including the sparated colons
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Vec::is_empty"))]
     pub tags: Vec<Cow<'a, str>>,
-    /// headline keyword
+    /// Headline title keyword
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub keyword: Option<Cow<'a, str>>,
+    /// Raw headline's text, without the stars and the tags
     pub raw: Cow<'a, str>,
+    /// Planning elemenet associated to this headline
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub planning: Option<Box<Planning<'a>>>,
+    /// Property drawer associated to this headline
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "HashMap::is_empty"))]
     pub properties: HashMap<Cow<'a, str>, Cow<'a, str>>,
 }
@@ -106,18 +110,26 @@ impl Title<'_> {
         ))
     }
 
+    // TODO: fn is_archived(&self) -> bool { }
+    // TODO: fn is_commented(&self) -> bool { }
+    // TODO: fn is_quoted(&self) -> bool { }
+    // TODO: fn is_footnote_section(&self) -> bool { }
+
+    /// Returns this headline's closed timestamp, or `None` if not set.
     pub fn closed(&self) -> Option<&Timestamp> {
         self.planning
             .as_ref()
             .and_then(|planning| planning.closed.as_ref())
     }
 
+    /// Returns this headline's scheduled timestamp, or `None` if not set.
     pub fn scheduled(&self) -> Option<&Timestamp> {
         self.planning
             .as_ref()
             .and_then(|planning| planning.scheduled.as_ref())
     }
 
+    /// Returns this headline's deadline timestamp, or `None` if not set.
     pub fn deadline(&self) -> Option<&Timestamp> {
         self.planning
             .as_ref()