Refactor some docs, fix some grammar

4 files changed, 25 insertions, 18 deletions

diff --git a/src/construct/definition.rs b/src/construct/definition.rs
index aca22a6..af94d12 100644
--- a/src/construct/definition.rs
+++ b/src/construct/definition.rs
@@ -3,7 +3,7 @@
 //! They’re formed with the following BNF:
 //!
 //! ```bnf
-//! definition ::= label ':' whitespace destination [ whitespace title ] [ space_or_tab ]
+//! definition ::= label ':' [ whitespace ] destination [ whitespace title ] [ space_or_tab ]
 //!
 //! ; See the `destination`, `title`, and `label` constructs for the BNF of
 //! ; those parts.
@@ -20,7 +20,7 @@
 //! See [*§ 4.5.1 The `a` element*][html-a] and
 //! [*§ 4.8.3 The `img` element*][html-img] in the HTML spec for more info.
 //!
-//! The `label`, `destination`, and `title` parts are interpreted as the
+//! The `destination`, `label`, and `title` parts are interpreted as the
 //! [string][] content type.
 //! That means that [character escapes][character_escape] and
 //! [character references][character_reference] are allowed.
@@ -28,7 +28,7 @@
 //! Definitions match to references through their label.
 //! To match, both labels must be equal after normalizing with
 //! [`normalize_identifier`][normalize_identifier].
-//! One definitions can match to multiple references.
+//! One definition can match to multiple references.
 //! Multiple definitions with the same, normalized, identifier are ignored: the
 //! first definition is preferred.
 //! To illustrate, the definition with a destination of `x` wins:
@@ -53,7 +53,7 @@
 //!
 //! For info on how to encode characters in URLs, see
 //! [`destination`][destination].
-//! For info on how to characters are encoded as `href` on `<a>` or `src` on
+//! For info on how characters are encoded as `href` on `<a>` or `src` on
 //! `<img>` when compiling, see
 //! [`sanitize_uri`][sanitize_uri].
 //!
diff --git a/src/construct/hard_break_escape.rs b/src/construct/hard_break_escape.rs
index 4458ccb..1e755a3 100644
--- a/src/construct/hard_break_escape.rs
+++ b/src/construct/hard_break_escape.rs
@@ -15,7 +15,8 @@
 //! It is also possible to create a hard break with a
 //! [hard break (trailing)][hard_break_trailing].
 //! That construct is not recommended because trailing spaces are typically
-//! invisible in editors, or even automatically removed, making them to use.
+//! invisible in editors, or even automatically removed, making them hard to
+//! use.
 //!
 //! It is also possible to escape punctuation characters with a similar
 //! construct: a [character escape][character_escape] is a backslash followed
diff --git a/src/construct/heading_setext.rs b/src/construct/heading_setext.rs
index 63f3c30..03a2e55 100644
--- a/src/construct/heading_setext.rs
+++ b/src/construct/heading_setext.rs
@@ -25,8 +25,10 @@
 //! headings.
 //! Due to this limitation, it is recommended to use atx headings.
 //!
-//! [Thematic breaks][thematic_break] formed with dashes (without whitespace)
-//! can also form heading (setext).
+//! [Thematic breaks][thematic_break] formed with dashes and without whitespace
+//! could be interpreted as a heading (setext).
+//! Which one forms depends on whether there is text directly in fron of the
+//! sequence.
 //!
 //! > 🏛 **Background**: the word *setext* originates from a small markup
 //! > language by Ian Feldman from 1991.
diff --git a/src/construct/label_end.rs b/src/construct/label_end.rs
index f43a740..888355b 100644
--- a/src/construct/label_end.rs
+++ b/src/construct/label_end.rs
@@ -30,7 +30,7 @@
 //! [definition][].
 //! Full references (`[x][y]`) match to definitions through their explicit,
 //! second, label (`y`).
-//! Collapsed labels (`[x][]`) and shortcut labels (`[x]`) match by
+//! Collapsed references (`[x][]`) and shortcut references (`[x]`) match by
 //! interpreting the text provided between the first, implicit, label (`x`).
 //! To match, the effective label of the reference must be equal to the label
 //! of the definition after normalizing with
@@ -50,11 +50,11 @@
 //! When the resource or reference matches, the destination forms the `href`
 //! attribute in case of a [label start (link)][label_start_link], and an
 //! `src` attribute otherwise.
-//! The title is, optionally, formed, on either `<a>` or `<img>`.
+//! The title is formed, optionally, on either `<a>` or `<img>`.
 //!
 //! For info on how to encode characters in URLs, see
 //! [`destination`][destination].
-//! For info on how to characters are encoded as `href` on `<a>` or `src` on
+//! For info on how characters are encoded as `href` on `<a>` or `src` on
 //! `<img>` when compiling, see
 //! [`sanitize_uri`][sanitize_uri].
 //!
@@ -78,9 +78,10 @@
 //! ```
 //!
 //! It is possible to use images in links.
-//! It’s, somewhat, possible to have links in images (the text will be used,
-//! not the HTML, see above).
-//! But it’s not possible to use links in links, and the “deepest” link wins.
+//! It’s somewhat possible to have links in images (the text will be used, not
+//! the HTML, see above).
+//! But it’s not possible to use links in links.
+//! The “deepest” link wins.
 //! To illustrate:
 //!
 //! ```markdown
@@ -95,8 +96,9 @@
 //!
 //! This limiation is imposed because links in links is invalid according to
 //! HTML.
-//! Technically though, it is still possible to construct them by using an
-//! [autolink][] in a link, but you definitely should not do that.
+//! Technically though, in markdown it is still possible to construct them by
+//! using an [autolink][] in a link.
+//! You definitely should not do that.
 //!
 //! ## Tokens
 //!
@@ -140,7 +142,7 @@
 //! [definition]: crate::construct::definition
 //! [autolink]: crate::construct::autolink
 //! [sanitize_uri]: crate::util::sanitize_uri::sanitize_uri
-//! [normalize_identifier]: crate::util::normalize_identifier
+//! [normalize_identifier]: crate::util::normalize_identifier::normalize_identifier
 //! [html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element
 //! [html-img]: https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
 
@@ -169,8 +171,10 @@ struct Info {
     media: Media,
 }
 
-/// Resolve media: turn correct label start (image, link) and label end
-/// into links and images, or turn them back into data.
+/// Resolve media.
+///
+/// This turns correct label start (image, link) and label end into links and
+/// images, or turns them back into data.
 #[allow(clippy::too_many_lines)]
 pub fn resolve_media(tokenizer: &mut Tokenizer) -> Vec<Event> {
     let mut left: Vec<LabelStart> = tokenizer.label_start_list_loose.drain(..).collect();