docs: document pre_blank and post_blank

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<Cow<'a, str>>,
     /// 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<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,
 }
 
@@ -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<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,
 }
 
@@ -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<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,
 }
 
@@ -113,9 +121,10 @@ impl VerseBlock<'_> {
 pub struct CommentBlock<'a> {
     #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
     pub data: Option<Cow<'a, str>>,
-    /// 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<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,
 }
 
@@ -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,
 }
 

src/elements/clock.rs

@@ -31,7 +31,8 @@ pub enum Clock<'a> {
         delay: Option<Cow<'a, str>>,
         /// 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<Cow<'a, str>>,
         #[cfg_attr(feature = "ser", serde(skip_serializing_if = "Option::is_none"))]
         delay: Option<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,
     },
 }

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,
 }
 

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,
 }
 

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<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 drawer's line and next non-blank
+    /// line or buffer's end
     pub post_blank: usize,
 }
 

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,
 }
 

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,
 }
 

src/elements/keyword.rs

@@ -21,7 +21,8 @@ pub struct Keyword<'a> {
     pub optional: Option<Cow<'a, str>>,
     /// 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,
 }
 

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,
 }
 

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>, 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,
 }
 

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(())