From 1cc22d49ab944878967d68b366629616006ba62b Mon Sep 17 00:00:00 2001 From: PoiScript Date: Wed, 30 Oct 2019 11:33:01 +0800 Subject: [PATCH] docs: document `pre_blank` and `post_blank` --- src/elements/block.rs | 40 ++++++++++++++++++++++++------------- src/elements/clock.rs | 6 ++++-- src/elements/comment.rs | 3 +++ src/elements/drawer.rs | 6 ++++-- src/elements/dyn_block.rs | 6 ++++-- src/elements/fixed_width.rs | 3 +++ src/elements/fn_def.rs | 3 ++- src/elements/keyword.rs | 7 +++++-- src/elements/rule.rs | 2 ++ src/elements/title.rs | 3 ++- src/headline.rs | 4 ++-- 11 files changed, 57 insertions(+), 26 deletions(-) diff --git a/src/elements/block.rs b/src/elements/block.rs index 744430f..d664ced 100644 --- a/src/elements/block.rs +++ b/src/elements/block.rs @@ -12,14 +12,16 @@ use crate::parsers::{blank_lines, line, take_lines_while}; #[cfg_attr(test, derive(PartialEq))] #[cfg_attr(feature = "ser", derive(serde::Serialize))] pub struct SpecialBlock<'a> { - /// Optional block parameters + /// Block parameters #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub parameters: Option>, /// Block name pub name: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between first block's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -42,9 +44,11 @@ pub struct QuoteBlock<'a> { /// Optional block parameters #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub parameters: Option>, - /// Numbers of blank lines + /// Numbers of blank lines between first block's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -66,9 +70,11 @@ pub struct CenterBlock<'a> { /// Optional block parameters #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub parameters: Option>, - /// Numbers of blank lines + /// Numbers of blank lines between first block's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -90,9 +96,11 @@ pub struct VerseBlock<'a> { /// Optional block parameters #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub parameters: Option>, - /// Numbers of blank lines + /// Numbers of blank lines between first block's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -113,9 +121,10 @@ impl VerseBlock<'_> { pub struct CommentBlock<'a> { #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub data: Option>, - /// Comment, without block's boundaries + /// Comment block contents pub contents: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -138,7 +147,8 @@ pub struct ExampleBlock<'a> { pub data: Option>, /// Block contents pub contents: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -160,7 +170,8 @@ pub struct ExportBlock<'a> { pub data: Cow<'a, str>, /// Block contents pub contents: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } @@ -184,7 +195,8 @@ pub struct SourceBlock<'a> { /// Language of the code in the block pub language: Cow<'a, str>, pub arguments: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between last block's line and next non-blank line + /// or buffer's end pub post_blank: usize, } diff --git a/src/elements/clock.rs b/src/elements/clock.rs index a0b0b58..407d245 100644 --- a/src/elements/clock.rs +++ b/src/elements/clock.rs @@ -31,7 +31,8 @@ pub enum Clock<'a> { delay: Option>, /// Clock duration duration: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between the clock line and next non-blank + /// line or buffer's end post_blank: usize, }, /// Running Clock @@ -42,7 +43,8 @@ pub enum Clock<'a> { repeater: Option>, #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] delay: Option>, - /// Numbers of blank lines + /// Numbers of blank lines between the clock line and next non-blank + /// line or buffer's end post_blank: usize, }, } diff --git a/src/elements/comment.rs b/src/elements/comment.rs index bf50bc4..2f029ac 100644 --- a/src/elements/comment.rs +++ b/src/elements/comment.rs @@ -5,7 +5,10 @@ use crate::parsers::{blank_lines, take_lines_while}; #[derive(Debug, Default)] #[cfg_attr(feature = "ser", derive(serde::Serialize))] pub struct Comment<'a> { + /// Comments value, with pound signs pub value: Cow<'a, str>, + /// Numbers of blank lines between last comment's line and next non-blank + /// line or buffer's end pub post_blank: usize, } diff --git a/src/elements/drawer.rs b/src/elements/drawer.rs index 73eef7d..bbe57f2 100644 --- a/src/elements/drawer.rs +++ b/src/elements/drawer.rs @@ -16,9 +16,11 @@ use crate::parsers::{blank_lines, eol, line, take_lines_while}; pub struct Drawer<'a> { /// Drawer name pub name: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between first drawer's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last drawer's line and next non-blank + /// line or buffer's end pub post_blank: usize, } diff --git a/src/elements/dyn_block.rs b/src/elements/dyn_block.rs index 77c8fa8..e919450 100644 --- a/src/elements/dyn_block.rs +++ b/src/elements/dyn_block.rs @@ -19,9 +19,11 @@ pub struct DynBlock<'a> { /// Block argument #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))] pub arguments: Option>, - /// Numbers of blank lines + /// Numbers of blank lines between first block's line and next non-blank + /// line pub pre_blank: usize, - /// Numbers of blank lines + /// Numbers of blank lines between last drawer's line and next non-blank + /// line or buffer's end pub post_blank: usize, } diff --git a/src/elements/fixed_width.rs b/src/elements/fixed_width.rs index bf4feac..7e29ec3 100644 --- a/src/elements/fixed_width.rs +++ b/src/elements/fixed_width.rs @@ -6,7 +6,10 @@ use crate::parsers::{blank_lines, take_lines_while}; #[cfg_attr(test, derive(PartialEq))] #[cfg_attr(feature = "ser", derive(serde::Serialize))] pub struct FixedWidth<'a> { + /// Fxied width value pub value: Cow<'a, str>, + /// Numbers of blank lines between last fixed width's line and next + /// non-blank line or buffer's end pub post_blank: usize, } diff --git a/src/elements/fn_def.rs b/src/elements/fn_def.rs index 960357f..a94feaf 100644 --- a/src/elements/fn_def.rs +++ b/src/elements/fn_def.rs @@ -16,7 +16,8 @@ use crate::parsers::{blank_lines, line}; pub struct FnDef<'a> { /// Footnote label, used for refrence pub label: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between last footnote definition's line and next + /// non-blank line or buffer's end pub post_blank: usize, } diff --git a/src/elements/keyword.rs b/src/elements/keyword.rs index f393771..7c7dcdc 100644 --- a/src/elements/keyword.rs +++ b/src/elements/keyword.rs @@ -21,7 +21,8 @@ pub struct Keyword<'a> { pub optional: Option>, /// Keyword value pub value: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between keyword line and next non-blank line or + /// buffer's end pub post_blank: usize, } @@ -41,8 +42,10 @@ impl Keyword<'_> { #[cfg_attr(feature = "ser", derive(serde::Serialize))] #[derive(Debug)] pub struct BabelCall<'a> { + /// Babel call value pub value: Cow<'a, str>, - /// Numbers of blank lines + /// Numbers of blank lines between babel call line and next non-blank line + /// or buffer's end pub post_blank: usize, } diff --git a/src/elements/rule.rs b/src/elements/rule.rs index eda64fd..1b85762 100644 --- a/src/elements/rule.rs +++ b/src/elements/rule.rs @@ -6,6 +6,8 @@ use crate::parsers::{blank_lines, eol}; #[cfg_attr(test, derive(PartialEq))] #[cfg_attr(feature = "ser", derive(serde::Serialize))] pub struct Rule { + /// Numbers of blank lines between rule line and next non-blank line or + /// buffer's end pub post_blank: usize, } diff --git a/src/elements/title.rs b/src/elements/title.rs index a154426..0814651 100644 --- a/src/elements/title.rs +++ b/src/elements/title.rs @@ -44,7 +44,8 @@ pub struct Title<'a> { /// Property drawer associated to this headline #[cfg_attr(feature = "ser", serde(skip_serializing_if = "HashMap::is_empty"))] pub properties: HashMap, Cow<'a, str>>, - /// Numbers of blank lines + /// Numbers of blank lines between last title's line and next non-blank line + /// or buffer's end pub post_blank: usize, } diff --git a/src/headline.rs b/src/headline.rs index e584419..aed600c 100644 --- a/src/headline.rs +++ b/src/headline.rs @@ -369,7 +369,7 @@ impl Headline { ), } - *org.arena[ttl_n].get_mut() = Element::Title(ttl); + org[ttl_n] = Element::Title(ttl); Headline { lvl, @@ -519,7 +519,7 @@ impl Headline { } self.lvl = lvl; self.title_mut(org).level = lvl; - if let Element::Headline { level } = org.arena[self.hdl_n].get_mut() { + if let Element::Headline { level } = &mut org[self.hdl_n] { *level = lvl; } Ok(())