Refactor to improve some module docs

12 files changed, 24 insertions, 22 deletions

diff --git a/src/construct/autolink.rs b/src/construct/autolink.rs
index 21f8fa5..0819f3a 100644
--- a/src/construct/autolink.rs
+++ b/src/construct/autolink.rs
@@ -27,7 +27,7 @@
 //!
 //! The grammar for autolinks is quite strict and prohibits the use of ASCII control
 //! characters or spaces.
-//! To use non-ascii characters and otherwise impossible characters, in URLs,
+//! To use non-ascii characters and otherwise impossible characters in URLs,
 //! you can use percent encoding:
 //!
 //! ```markdown
diff --git a/src/construct/blank_line.rs b/src/construct/blank_line.rs
index 5be406d..475883d 100644
--- a/src/construct/blank_line.rs
+++ b/src/construct/blank_line.rs
@@ -13,7 +13,7 @@
 //! followed by an eol (line ending) or eof (end of file).
 //!
 //! Blank lines are sometimes needed, such as to differentiate a [paragraph][]
-//! from another paragraph.
+//! from a definition.
 //! In several cases, blank lines are not needed between flow constructs,
 //! such as between two [heading (atx)][heading_atx]s.
 //! Sometimes, whether blank lines are present, changes the behavior of how
@@ -26,8 +26,8 @@
 //!
 //! ## HTML
 //!
-//! Blank lines do not relate an element in HTML, except for the role they play
-//! when inside or between [list items][list_item].
+//! Blank lines do not relate to an element in HTML, except for the role they
+//! play when inside or between [list items][list_item].
 //!
 //! ## Recommendation
 //!
diff --git a/src/construct/block_quote.rs b/src/construct/block_quote.rs
index 11783d0..ec7b7f0 100644
--- a/src/construct/block_quote.rs
+++ b/src/construct/block_quote.rs
@@ -12,7 +12,7 @@
 //!
 //! Further lines that are not prefixed with `block_quote_cont` cause the block
 //! quote to be exited, except when those lines are lazy continuation.
-//! Like so many things in markdown, block quotes too, are complex.
+//! Like so many things in markdown, block quotes too are complex.
 //! See [*§ Phase 1: block structure* in `CommonMark`][commonmark-block] for
 //! more on parsing details.
 //!
diff --git a/src/construct/character_escape.rs b/src/construct/character_escape.rs
index 67946a0..471fc8c 100644
--- a/src/construct/character_escape.rs
+++ b/src/construct/character_escape.rs
@@ -11,11 +11,10 @@
 //!
 //! Like much of markdown, there are no “invalid” character escapes: just a
 //! slash, or a slash followed by anything other than an ASCII punctuation
-//! character, is exactly that: just a slash.
+//! character, is just a slash.
 //!
-//! To escape (almost all) arbitrary characters instead of only ASCII
-//! punctuation, use a [character reference][character_reference] instead
-//! (as in, `&`, `{`, or say `	`).
+//! To escape other characters, use a [character reference][character_reference]
+//! instead (as in, `&`, `{`, or say `	`).
 //!
 //! It is also possible to escape a line ending in text with a similar
 //! construct: a [hard break (escape)][hard_break_escape] is a backslash followed
diff --git a/src/construct/gfm_footnote_definition.rs b/src/construct/gfm_footnote_definition.rs
index d3f72d7..99758f9 100644
--- a/src/construct/gfm_footnote_definition.rs
+++ b/src/construct/gfm_footnote_definition.rs
@@ -7,7 +7,7 @@
 //!
 //! ```bnf
 //! ; Restriction: `label` must start with `^` (and not be empty after it).
-//! ; See the `label` construct for the BNF of that parts.
+//! ; See the `label` construct for the BNF of that part.
 //! gfm_footnote_definition_start ::= label ':' *space_or_tab
 //!
 //! ; Restriction: blank line allowed.
@@ -17,7 +17,7 @@
 //! Further lines that are not prefixed with `gfm_footnote_definition_cont`
 //! cause the footnote definition to be exited, except when those lines are
 //! lazy continuation or blank.
-//! Like so many things in markdown, footnote definition too, are complex.
+//! Like so many things in markdown, footnote definition too are complex.
 //! See [*§ Phase 1: block structure* in `CommonMark`][commonmark_block] for
 //! more on parsing details.
 //!
diff --git a/src/construct/heading_setext.rs b/src/construct/heading_setext.rs
index 1e6fd00..73b89c6 100644
--- a/src/construct/heading_setext.rs
+++ b/src/construct/heading_setext.rs
@@ -6,7 +6,7 @@
 //! (<small>see [construct][crate::construct] for character groups</small>):
 //!
 //! ```bnf
-//! heading_setext ::= paragraph eol *space_or_tab (1*'-' | 1*'=')  *space_or_tab
+//! heading_setext ::= paragraph eol *space_or_tab (1*'-' | 1*'=') *space_or_tab
 //!
 //! ; See the `paragraph` construct for the BNF of that part.
 //! ```
diff --git a/src/construct/html_flow.rs b/src/construct/html_flow.rs
index 3f6e19a..3de70de 100644
--- a/src/construct/html_flow.rs
+++ b/src/construct/html_flow.rs
@@ -30,7 +30,7 @@
 //! As this construct occurs in flow, like all flow constructs, it must be
 //! followed by an eol (line ending) or eof (end of file).
 //!
-//! The grammar for HTML in markdown does not resemble the rules of parsing
+//! The grammar for HTML in markdown does not follow the rules of parsing
 //! HTML according to the [*§ 13.2 Parsing HTML documents* in the HTML
 //! spec][html_parsing].
 //! As such, HTML in markdown *resembles* HTML, but is instead a (naïve?)
@@ -52,11 +52,11 @@
 //! For example:
 //!
 //! ```markdown
-//! <div>This is a <code>div</code> but *this* is not emphasis.</div>
+//! <div>This is <code>code</code> but this is not *emphasis*.</div>
 //!
 //! <div>
 //!
-//! This is a paragraph in a `div` and *this* is emphasis.
+//! This is a paragraph in a `div` and with `code` and *emphasis*.
 //!
 //! </div>
 //! ```
diff --git a/src/construct/html_text.rs b/src/construct/html_text.rs
index d40361d..7812da6 100644
--- a/src/construct/html_text.rs
+++ b/src/construct/html_text.rs
@@ -23,7 +23,7 @@
 //! attribute_value ::= '"' *(byte - '"') '"' | "'" *(byte - "'")  "'" | 1*(text - '"' - "'" - '/' - '<' - '=' - '>' - '`')
 //! ```
 //!
-//! The grammar for HTML in markdown does not resemble the rules of parsing
+//! The grammar for HTML in markdown does not follow the rules of parsing
 //! HTML according to the [*§ 13.2 Parsing HTML documents* in the HTML
 //! spec][html_parsing].
 //! See the related flow construct [HTML (flow)][html_flow] for more info.
diff --git a/src/construct/list_item.rs b/src/construct/list_item.rs
index a4f166d..87cf0b1 100644
--- a/src/construct/list_item.rs
+++ b/src/construct/list_item.rs
@@ -7,7 +7,7 @@
 //!
 //! ```bnf
 //! ; Restriction: if there is no space after the marker, the start must be followed by an `eol`.
-//! ; Restriction: if the first line after the marker is not blank and starts with `5( space_or_tab )`,
+//! ; Restriction: if the first line after the marker is not blank and starts with `5(space_or_tab)`,
 //! ; only the first `space_or_tab` is part of the start.
 //! list_item_start ::= '*' | '+' | '-' | 1*9(ascii_decimal) ('.' | ')') [1*4 space_or_tab]
 //!
@@ -18,7 +18,7 @@
 //!
 //! Further lines that are not prefixed with `list_item_cont` cause the list
 //! item to be exited, except when those lines are lazy continuation or blank.
-//! Like so many things in markdown, list items too, are complex.
+//! Like so many things in markdown, list items too are complex.
 //! See [*§ Phase 1: block structure* in `CommonMark`][commonmark_block] for
 //! more on parsing details.
 //!
diff --git a/src/construct/mdx_esm.rs b/src/construct/mdx_esm.rs
index 4fb6b50..47e11a3 100644
--- a/src/construct/mdx_esm.rs
+++ b/src/construct/mdx_esm.rs
@@ -13,7 +13,7 @@
 //!
 //! This construct must be followed by a blank line or eof (end of file).
 //! It can include blank lines if [`MdxEsmParse`][crate::MdxEsmParse] passed in
-//! `options.mdx_esm_parse` allows it.
+//! [`ParseOptions`][parse_options] allows it.
 //!
 //! ## Tokens
 //!
@@ -27,6 +27,7 @@
 //! *   [`mdxjs.com`](https://mdxjs.com)
 //!
 //! [flow]: crate::construct::flow
+//! [parse_options]: crate::ParseOptions
 
 use crate::event::Name;
 use crate::state::{Name as StateName, State};
diff --git a/src/construct/partial_bom.rs b/src/construct/partial_bom.rs
index 3f772e9..f6786d6 100644
--- a/src/construct/partial_bom.rs
+++ b/src/construct/partial_bom.rs
@@ -25,6 +25,7 @@ use crate::event::Name;
 use crate::state::{Name as StateName, State};
 use crate::tokenizer::Tokenizer;
 
+/// Bytes of a BOM.
 const BOM: [u8; 3] = [0xEF, 0xBB, 0xBF];
 
 /// Before BOM.
diff --git a/src/construct/raw_text.rs b/src/construct/raw_text.rs
index 6a35608..9d5fdea 100644
--- a/src/construct/raw_text.rs
+++ b/src/construct/raw_text.rs
@@ -86,9 +86,9 @@
 //! Notably, GitHub currently has a really weird crappy client-side regex-based
 //! thing.
 //! But on your own (math-heavy?) site it can be great!
-//! You can set `options.math_text_single_dollar: false` to improve this, as it
-//! prevents single dollars from being seen as math, and thus prevents normal
-//! dollars in text from being seen as math.
+//! You can set [`parse_options.math_text_single_dollar: false`][parse_options]
+//! to improve this, as it prevents single dollars from being seen as math, and
+//! thus prevents normal dollars in text from being seen as math.
 //!
 //! ## Tokens
 //!
@@ -113,6 +113,7 @@
 //! [code_indented]: crate::construct::code_indented
 //! [raw_flow]: crate::construct::raw_flow
 //! [html_code]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element
+//! [parse_options]: crate::ParseOptions
 
 use crate::event::Name;
 use crate::state::{Name as StateName, State};