From f235354046822c89f99f44fec0e8959e31352bb9 Mon Sep 17 00:00:00 2001 From: PoiScript Date: Mon, 16 Sep 2019 22:31:57 +0800 Subject: [PATCH] docs(elements): some doc comment for struct and fields --- orgize/src/elements/block.rs | 24 ++++++++++++++++++++++++ orgize/src/elements/clock.rs | 20 +++++++++++--------- orgize/src/elements/cookie.rs | 2 ++ orgize/src/elements/drawer.rs | 2 ++ orgize/src/elements/dyn_block.rs | 3 +++ orgize/src/elements/fn_def.rs | 2 ++ orgize/src/elements/fn_ref.rs | 2 ++ orgize/src/elements/inline_call.rs | 5 +++++ orgize/src/elements/inline_src.rs | 4 ++++ orgize/src/elements/keyword.rs | 4 ++++ orgize/src/elements/link.rs | 2 ++ orgize/src/elements/list.rs | 3 +++ orgize/src/elements/macros.rs | 3 +++ orgize/src/elements/mod.rs | 2 +- orgize/src/elements/planning.rs | 8 ++++---- orgize/src/elements/snippet.rs | 7 +++++-- orgize/src/elements/table.rs | 10 ++++++---- orgize/src/elements/target.rs | 2 ++ orgize/src/elements/timestamp.rs | 16 ++++------------ orgize/src/elements/title.rs | 20 ++++++++++++++++---- 20 files changed, 105 insertions(+), 36 deletions(-) diff --git a/orgize/src/elements/block.rs b/orgize/src/elements/block.rs index eed973a..a7a3eb8 100644 --- a/orgize/src/elements/block.rs +++ b/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>, + /// 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>, } @@ -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>, } @@ -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>, } @@ -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>, + /// 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>, + /// 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 { } + // TODO: fn retain_labels() -> bool { } } pub(crate) fn parse_block_element(input: &str) -> IResult<&str, (&str, Option<&str>, &str)> { diff --git a/orgize/src/elements/clock.rs b/orgize/src/elements/clock.rs index fda4678..cb0f865 100644 --- a/orgize/src/elements/clock.rs +++ b/orgize/src/elements/clock.rs @@ -11,26 +11,28 @@ use nom::{ use crate::elements::{Datetime, Timestamp}; use crate::parsers::eol; -/// clock elements -/// -/// there are two types of clock: *closed* clock and *running* clock. +/// Clock Element #[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>, #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] delay: Option>, + /// 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>, @@ -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 { diff --git a/orgize/src/elements/cookie.rs b/orgize/src/elements/cookie.rs index c4b1fb8..90a7d7b 100644 --- a/orgize/src/elements/cookie.rs +++ b/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>, } diff --git a/orgize/src/elements/drawer.rs b/orgize/src/elements/drawer.rs index d375235..5cb94a2 100644 --- a/orgize/src/elements/drawer.rs +++ b/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>, } diff --git a/orgize/src/elements/dyn_block.rs b/orgize/src/elements/dyn_block.rs index c665aaa..6a1050a 100644 --- a/orgize/src/elements/dyn_block.rs +++ b/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>, } diff --git a/orgize/src/elements/fn_def.rs b/orgize/src/elements/fn_def.rs index 13aad70..b15fd2b 100644 --- a/orgize/src/elements/fn_def.rs +++ b/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>, } diff --git a/orgize/src/elements/fn_ref.rs b/orgize/src/elements/fn_ref.rs index b8dee48..770f403 100644 --- a/orgize/src/elements/fn_ref.rs +++ b/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>, diff --git a/orgize/src/elements/inline_call.rs b/orgize/src/elements/inline_call.rs index dfbc0b2..22b67f5 100644 --- a/orgize/src/elements/inline_call.rs +++ b/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>, + /// 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>, } diff --git a/orgize/src/elements/inline_src.rs b/orgize/src/elements/inline_src.rs index 54e75f6..cb571a5 100644 --- a/orgize/src/elements/inline_src.rs +++ b/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>, + /// Source code pub body: Cow<'a, str>, } diff --git a/orgize/src/elements/keyword.rs b/orgize/src/elements/keyword.rs index 13c61c2..0f367d1 100644 --- a/orgize/src/elements/keyword.rs +++ b/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>, + /// 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)] diff --git a/orgize/src/elements/link.rs b/orgize/src/elements/link.rs index 7f73b16..15292ef 100644 --- a/orgize/src/elements/link.rs +++ b/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>, diff --git a/orgize/src/elements/list.rs b/orgize/src/elements/list.rs index 6bbb966..ed625b0 100644 --- a/orgize/src/elements/list.rs +++ b/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>, } diff --git a/orgize/src/elements/macros.rs b/orgize/src/elements/macros.rs index d972b0e..77b304e 100644 --- a/orgize/src/elements/macros.rs +++ b/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>, } diff --git a/orgize/src/elements/mod.rs b/orgize/src/elements/mod.rs index a059107..8a48a31 100644 --- a/orgize/src/elements/mod.rs +++ b/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))] diff --git a/orgize/src/elements/planning.rs b/orgize/src/elements/planning.rs index 91b482c..c37e988 100644 --- a/orgize/src/elements/planning.rs +++ b/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>, - /// 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>, - /// 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>, } diff --git a/orgize/src/elements/snippet.rs b/orgize/src/elements/snippet.rs index 3ae17a7..865f6f0 100644 --- a/orgize/src/elements/snippet.rs +++ b/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(( diff --git a/orgize/src/elements/table.rs b/orgize/src/elements/table.rs index b56cca5..41407e8 100644 --- a/orgize/src/elements/table.rs +++ b/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> }, + /// "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( - feature = "ser", - serde(tag = "table_row_type", rename_all = "kebab-case") -)] +#[cfg_attr(feature = "ser", serde(tag = "table_row_type"))] +#[cfg_attr(feature = "ser", serde(rename_all = "kebab-case"))] pub enum TableRow { Standard, Rule, diff --git a/orgize/src/elements/target.rs b/orgize/src/elements/target.rs index cf6f125..44a1c2d 100644 --- a/orgize/src/elements/target.rs +++ b/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>, } diff --git a/orgize/src/elements/timestamp.rs b/orgize/src/elements/timestamp.rs index dfe3a31..3d5afbc 100644 --- a/orgize/src/elements/timestamp.rs +++ b/orgize/src/elements/timestamp.rs @@ -8,14 +8,7 @@ use nom::{ IResult, }; -/// Datetime -/// -/// # Syntax -/// -/// ```text -/// YYYY-MM-DD DAYNAME -/// ``` -/// +/// Orgize Datetime Struct #[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( - feature = "ser", - serde(tag = "timestamp_type", rename_all = "kebab-case") -)] +#[cfg_attr(feature = "ser", serde(rename_all = "kebab-case"))] +#[cfg_attr(feature = "ser", serde(tag = "timestamp_type"))] #[derive(Debug)] pub enum Timestamp<'a> { Active { diff --git a/orgize/src/elements/title.rs b/orgize/src/elements/title.rs index 444e1e0..f231f23 100644 --- a/orgize/src/elements/title.rs +++ b/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, - /// 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>, - /// headline keyword + /// Headline title keyword #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub keyword: Option>, + /// 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>>, + /// Property drawer associated to this headline #[cfg_attr(feature = "ser", serde(skip_serializing_if = "HashMap::is_empty"))] pub properties: HashMap, 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()