chore: Review the doc comments for consistency in formatting (#183)

parser/src/attributes/attrlist.rs

@@ -8,7 +8,7 @@ use crate::{
 };
 
 /// The source text that’s used to define attributes for an element is referred
-/// to as an attrlist. An attrlist is always enclosed in a pair of square
+/// to as an **attrlist.** An attrlist is always enclosed in a pair of square
 /// brackets. This applies for block attributes as well as attributes on a block
 /// or inline macro. The processor splits the attrlist into individual attribute
 /// entries, determines whether each entry is a positional or named attribute,
@@ -21,10 +21,10 @@ pub struct Attrlist<'src> {
 }
 
 impl<'src> Attrlist<'src> {
-    /// IMPORTANT: This `source` span passed to this function should NOT include
-    /// the opening or closing square brackets for the attrlist. This is because
-    /// the rules for closing brackets differ when parsing inline, macro, and
-    /// block elements.
+    /// **IMPORTANT:** This `source` span passed to this function should NOT
+    /// include the opening or closing square brackets for the attrlist.
+    /// This is because the rules for closing brackets differ when parsing
+    /// inline, macro, and block elements.
     pub(crate) fn parse(source: Span<'src>) -> MatchAndWarnings<'src, MatchedItem<'src, Self>> {
         let mut after = source;
         let mut attributes: Vec<ElementAttribute> = vec![];
@@ -113,7 +113,8 @@ impl<'src> Attrlist<'src> {
 
     /// Returns the given (1-based) positional attribute.
     ///
-    /// IMPORTANT: Named attributes with names are disregarded when counting.
+    /// **IMPORTANT:** Named attributes with names are disregarded when
+    /// counting.
     pub fn nth_attribute(&'src self, n: usize) -> Option<&'src ElementAttribute<'src>> {
         if n == 0 {
             None
@@ -149,15 +150,15 @@ impl<'src> Attrlist<'src> {
     /// In the shorthand syntax, you prefix the name with a hash (`#`) in the
     /// first position attribute:
     ///
-    /// ```ignore
+    /// ```asciidoc
     /// [#goals]
     /// * Goal 1
     /// * Goal 2
     /// ```
     ///
     /// In the longhand syntax, you use a standard named attribute:
     ///
-    /// ```ignore
+    /// ```asciidoc
     /// [id=goals]
     /// * Goal 1
     /// * Goal 2
@@ -166,7 +167,7 @@ impl<'src> Attrlist<'src> {
     /// In the legacy block anchor syntax, you surround the name with double
     /// square brackets:
     ///
-    /// ```ignore
+    /// ```asciidoc
     /// [[goals]]
     /// * Goal 1
     /// * Goal 2

parser/src/attributes/element_attribute.rs

@@ -109,7 +109,11 @@ impl<'src> ElementAttribute<'src> {
         &self.name
     }
 
-    /// Return the shorthand items, if parsed via `parse_with_shorthand`.
+    /// Return the shorthand items, if applicable.
+    ///
+    /// Shorthand items are only parsed for certain element attributes. If this
+    /// attribute is not of the appropriate kind, this will return an empty
+    /// list.
     pub fn shorthand_items(&'src self) -> &'src Vec<Span<'src>> {
         &self.shorthand_items
     }
@@ -122,10 +126,10 @@ impl<'src> ElementAttribute<'src> {
             .copied()
     }
 
-    /// Return the id attribute from shorthand syntax.
+    /// Return the ID attribute from shorthand syntax.
     ///
-    /// If multiple id attributes were specified, only the first
-    /// match is returned. (Multiple ids are not supported.)
+    /// If multiple ID attributes were specified, only the first
+    /// match is returned. (Multiple IDs are not supported.)
     pub fn id(&'src self) -> Option<Span<'src>> {
         self.shorthand_items
             .iter()

parser/src/blocks/block.rs

@@ -12,14 +12,14 @@ use crate::{
     HasSpan, Span,
 };
 
-/// Block elements form the main structure of an AsciiDoc document, starting
+/// **Block elements** form the main structure of an AsciiDoc document, starting
 /// with the document itself.
 ///
-/// A block element (aka block) is a discrete, line-oriented chunk of content in
-/// an AsciiDoc document. Once parsed, that chunk of content becomes a block
-/// element in the parsed document model. Certain blocks may contain other
-/// blocks, so we say that blocks can be nested. The converter visits each block
-/// in turn, in document order, converting it to a corresponding chunk of
+/// A block element (aka **block**) is a discrete, line-oriented chunk of
+/// content in an AsciiDoc document. Once parsed, that chunk of content becomes
+/// a block element in the parsed document model. Certain blocks may contain
+/// other blocks, so we say that blocks can be nested. The converter visits each
+/// block in turn, in document order, converting it to a corresponding chunk of
 /// output.
 ///
 /// This enum represents all of the block types that are understood directly by

parser/src/blocks/is_block.rs

@@ -7,18 +7,19 @@ use crate::{
     HasSpan, Span,
 };
 
-/// Block elements form the main structure of an AsciiDoc document, starting
+/// **Block elements** form the main structure of an AsciiDoc document, starting
 /// with the document itself.
 ///
-/// A block element (aka block) is a discrete, line-oriented chunk of content in
-/// an AsciiDoc document. Once parsed, that chunk of content becomes a block
-/// element in the parsed document model. Certain blocks may contain other
-/// blocks, so we say that blocks can be nested. The converter visits each block
-/// in turn, in document order, converting it to a corresponding chunk of
+/// A block element (aka **block**) is a discrete, line-oriented chunk of
+/// content in an AsciiDoc document. Once parsed, that chunk of content becomes
+/// a block element in the parsed document model. Certain blocks may contain
+/// other blocks, so we say that blocks can be nested. The converter visits each
+/// block in turn, in document order, converting it to a corresponding chunk of
 /// output.
 ///
-/// This trait implements many of the same core methods as the [Block] enum but
-/// provides a mechanism for third-party code to extend the behavior of blocks.
+/// This trait implements many of the same core methods as the [`Block`] enum
+/// but provides a mechanism for third-party code to extend the behavior of
+/// blocks.
 pub trait IsBlock<'src>: HasSpan<'src> + Clone + Debug + Eq + PartialEq {
     /// Returns the [`ContentModel`] for this block.
     fn content_model(&self) -> ContentModel;
@@ -38,10 +39,10 @@ pub trait IsBlock<'src>: HasSpan<'src> + Clone + Debug + Eq + PartialEq {
     /// constants are viable.
     ///
     /// A block's context can be replaced by a block style that matches a
-    /// built-in context. Unlike [`raw_context`], that transformation _is_
+    /// built-in context. Unlike [`raw_context()`], that transformation _is_
     /// performed by this function.
     ///
-    /// [`raw_context`]: Self::raw_context
+    /// [`raw_context()`]: Self::raw_context
     fn resolved_context(&'src self) -> CowStr<'src> {
         if let Some(declared_style) = self.declared_style() {
             let declared_style = declared_style.data();
@@ -69,9 +70,9 @@ pub trait IsBlock<'src>: HasSpan<'src> + Clone + Debug + Eq + PartialEq {
     ///
     /// A block's context can be replaced by a block style that matches a
     /// built-in context. That transformation is only performed by
-    /// [`resolved_context`], not this function.
+    /// [`resolved_context()`], not this function.
     ///
-    /// [`resolved_context`]: Self::resolved_context
+    /// [`resolved_context()`]: Self::resolved_context
     fn raw_context(&self) -> CowStr<'src>;
 
     /// Returns the declared (uninterpreted) style for this block.
@@ -119,15 +120,15 @@ pub enum ContentModel {
     /// subject to normal substitutions) (e.g., a paragraph block)
     Simple,
 
-    /// A block that holds verbatim text (displayed "`as is`") (and subject to
+    /// A block that holds verbatim text (displayed "as is") (and subject to
     /// verbatim substitutions) (e.g., a listing block)
     Verbatim,
 
     /// A block that holds unprocessed content passed directly through to the
     /// output with no substitutions applied (e.g., a passthrough block)
     Raw,
 
-    /// Ablock that has no content (e.g., an image block)
+    /// A block that has no content (e.g., an image block)
     Empty,
 
     /// A special content model reserved for tables that enforces a fixed

parser/src/blocks/macro.rs

@@ -11,7 +11,7 @@ use crate::{
 ///
 /// This struct is returned when the block form of a *named macro* is detected.
 ///
-/// ```ignore
+/// ```asciidoc
 /// <name>::<target>?[<attrlist>?].
 /// ```
 #[derive(Clone, Debug, Eq, PartialEq)]
@@ -111,7 +111,7 @@ impl<'src> MacroBlock<'src> {
 
     /// Return the macro's attribute list.
     ///
-    /// IMPORTANT: This is the list of attributes _within_ the macro block
+    /// **IMPORTANT:** This is the list of attributes _within_ the macro block
     /// definition itself.
     ///
     /// See also [`attrlist()`] for attributes that can be defined before the

parser/src/blocks/mod.rs

@@ -1,22 +1,22 @@
-//! Block elements form the main structure of an AsciiDoc document, starting
+//! **Block elements** form the main structure of an AsciiDoc document, starting
 //! with the document itself.
 //!
-//! A block element (aka block) is a discrete, line-oriented chunk of content in
-//! an AsciiDoc document. Once parsed, that chunk of content becomes a block
-//! element in the parsed document model. Certain blocks may contain other
-//! blocks, so we say that blocks can be nested. The converter visits each block
-//! in turn, in document order, converting it to a corresponding chunk of
+//! A block element (aka **block**) is a discrete, line-oriented chunk of
+//! content in an AsciiDoc document. Once parsed, that chunk of content becomes
+//! a block element in the parsed document model. Certain blocks may contain
+//! other blocks, so we say that blocks can be nested. The converter visits each
+//! block in turn, in document order, converting it to a corresponding chunk of
 //! output.
 //!
 //! ## Design discussion
 //!
 //! There are two data structures that express blocks in the asciidoc-parser
 //! crate:
 //!
-//! * [Block] is an enum that contains the common built-in block types
+//! * [`Block`] is an enum that contains the common built-in block types
 //!   understood by this parser
-//! * [IsBlock] is a trait that describes the common properties of a block data
-//!   structure that might be provided outside of this crate
+//! * [`IsBlock`] is a trait that describes the common properties of a block
+//!   data structure that might be provided outside of this crate
 //!
 //! This duality exists because we sought to avoid the overhead of `Box<dyn
 //! Block>` throughout the codebase, but also needed to provide for

parser/src/blocks/section.rs

@@ -14,8 +14,8 @@ use crate::{
 /// sibling section, ancestor section, or end of document. Nested section levels
 /// must be sequential.
 ///
-/// WARNING: This is a very preliminary implementation. There are many TO DO
-/// items in this code.
+/// **WARNING:** This is a very preliminary implementation. There are many **TO
+/// DO** items in this code.
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct SectionBlock<'src> {
     level: usize,

parser/src/document/document.rs

@@ -43,11 +43,15 @@ impl<'src> Document<'src> {
     /// `asciidoc-parser` crate. Any UTF-16 content must be re-encoded as
     /// UTF-8 prior to parsing.
     ///
-    /// Any UTF-8 string is a valid AsciiDoc document, so there is no `Option`
-    /// or `Result` on this API. There may be any number of character sequences
-    /// that have ambiguous or potentially unintended meanings. For that reason,
-    /// a caller is advised to review the warnings provided via the
-    /// `Self::warnings` iterator.
+    /// # Warnings, not errors
+    ///
+    /// Any UTF-8 string is a valid AsciiDoc document, so this function does not
+    /// return an [`Option`] or [`Result`] data type. There may be any number of
+    /// character sequences that have ambiguous or potentially unintended
+    /// meanings. For that reason, a caller is advised to review the warnings
+    /// provided via the [`warnings()`] iterator.
+    ///
+    /// [`warnings()`]: Self::warnings
     pub fn parse(source: &'src str) -> Self {
         let source = Span::new(source);
         let i = source.discard_empty_lines();

parser/src/inlines/inline.rs

@@ -1,7 +1,7 @@
 use crate::{inlines::InlineMacro, span::MatchedItem, HasSpan, Span};
 
-/// An inline element is a phrase (i.e., span of content) within a block element
-/// or one of its attributes in an AsciiDoc document.
+/// An **inline element** is a phrase (i.e., span of content) within a block
+/// element or one of its attributes in an AsciiDoc document.
 #[derive(Clone, Debug, Eq, PartialEq)]
 #[non_exhaustive]
 pub enum Inline<'src> {

parser/src/inlines/macro.rs

@@ -1,11 +1,11 @@
 use crate::{span::MatchedItem, HasSpan, Span};
 
-/// An inline macro can be used in an inline context to create new inline
+/// An **inline macro** can be used in an inline context to create new inline
 /// content.
 ///
 /// This struct is returned when the inline form of a *named macro* is detected.
 ///
-/// ```ignore
+/// ```asciidoc
 /// <name>:<target>?[<attrlist>?].
 /// ```
 #[derive(Clone, Debug, Eq, PartialEq)]

parser/src/inlines/mod.rs

@@ -1,5 +1,5 @@
-//! An inline element is a phrase (i.e., span of content) within a block element
-//! or one of its attributes in an AsciiDoc document.
+//! An **inline element** is a phrase (i.e., span of content) within a block
+//! element or one of its attributes in an AsciiDoc document.
 
 mod inline;
 pub use inline::Inline;

parser/src/span/mod.rs

@@ -27,7 +27,7 @@ use std::ops::Deref;
 /// Annotated with 1-based line and column numbers relative to the
 /// beginning of the overall input stream.
 ///
-/// Called `Span` because its `data` member can be consumed
+/// Called `Span` because its [`data()`] member can be consumed
 /// to yield another `Span` with annotations for the end of the
 /// syntactic element in question.
 ///
@@ -47,6 +47,8 @@ use std::ops::Deref;
 ///     assert_eq!(span.byte_offset(), 0);
 /// }
 /// ```
+///
+/// [`data()`]: Self::data
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
 pub struct Span<'src> {
     data: &'src str,

parser/src/span/primitives.rs

@@ -60,9 +60,9 @@ impl<'src> Span<'src> {
     /// The single or double quote may be included in the string by preceding it
     /// with a backslash. No other backslash escape sequences are recognized.
     ///
-    /// IMPORTANT: The [`Span`] that is returned does not include the start or
-    /// ending quote, but _does_ include (without transformation) any escaped
-    /// quotes.
+    /// **IMPORTANT:** The [`Span`] that is returned does not include the start
+    /// or ending quote, but _does_ include (without transformation) any
+    /// escaped quotes.
     pub(crate) fn take_quoted_string(self) -> Option<MatchedItem<'src, Self>> {
         let mut chars = self.data.char_indices();
 

parser/src/strings.rs

@@ -32,8 +32,8 @@ use std::{
 
 pub(crate) const MAX_INLINE_STR_LEN: usize = 3 * std::mem::size_of::<isize>() - 2;
 
-/// Returned when trying to convert a `&str` into a `InlineStr`
-/// but it fails because it doesn't fit.
+/// Returned when trying to convert a `&str` into an [`InlineStr`] but it fails
+/// because it doesn't fit.
 #[derive(Debug)]
 pub struct StringTooLongError;