Add some improved docs

9 files changed, 34 insertions, 22 deletions

diff --git a/src/construct/blank_line.rs b/src/construct/blank_line.rs
index 7b7962b..7f794b9 100644
--- a/src/construct/blank_line.rs
+++ b/src/construct/blank_line.rs
@@ -1,4 +1,4 @@
-//! Blank lines are a construct that occurs in the flow content type.
+//! Blank lines are a construct that occurs in the [flow][] content type.
 //!
 //! They’re formed with the following BNF:
 //!
@@ -9,7 +9,7 @@
 //! Blank lines are sometimes needed, such as to differentiate a paragraph
 //! from another paragraph.
 //! In several cases, blank lines are not needed between flow constructs,
-//! such as between two headings.
+//! such as between two [heading (atx)][heading-atx]s.
 //! Sometimes, whether blank lines are present, changes the behavior of how
 //! HTML is rendered, such as whether blank lines are present between list
 //! items in a list.
@@ -23,7 +23,10 @@
 //! *   [`blank-line.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/blank-line.js)
 //! *   [*§ 4.9 Blank lines* in `CommonMark`](https://spec.commonmark.org/0.30/#blank-lines)
 //!
-//! <!-- To do: link `flow`, `heading`, `list`, `paragraph` -->
+//! [flow]: crate::content::flow
+//! [heading-atx]: crate::construct::heading_atx
+//!
+//! <!-- To do: link `list`, `paragraph` -->
 
 use crate::construct::partial_whitespace::start as whitespace;
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
diff --git a/src/construct/character_escape.rs b/src/construct/character_escape.rs
index 5ea995e..7bab42d 100644
--- a/src/construct/character_escape.rs
+++ b/src/construct/character_escape.rs
@@ -1,5 +1,5 @@
-//! Character escapes are a construct that occurs in the string and text
-//! content types.
+//! Character escapes are a construct that occurs in the [string][] and
+//! [text][] content types.
 //!
 //! They’re formed with the following BNF:
 //!
@@ -22,9 +22,11 @@
 //! *   [`character-escape.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/character-escape.js)
 //! *   [*§ 2.4 Backslash escapes* in `CommonMark`](https://spec.commonmark.org/0.30/#backslash-escapes)
 //!
+//! [string]: crate::content::string
+//! [text]: crate::content::text
 //! [character reference]: crate::construct::character_reference
 //!
-//! <!-- To do: link `hard_break_escape`, `string`, `text` -->
+//! <!-- To do: link `hard_break_escape` -->
 
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
 
diff --git a/src/construct/character_reference.rs b/src/construct/character_reference.rs
index 27275d5..943d70f 100644
--- a/src/construct/character_reference.rs
+++ b/src/construct/character_reference.rs
@@ -1,5 +1,5 @@
-//! Character references are a construct that occurs in the string and text
-//! content types.
+//! Character references are a construct that occurs in the [string][] and
+//! [text][] content types.
 //!
 //! They’re formed with the following BNF:
 //!
@@ -45,6 +45,8 @@
 //! *   [`character-reference.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/character-reference.js)
 //! *   [*§ 2.5 Entity and numeric character references* in `CommonMark`](https://spec.commonmark.org/0.30/#entity-and-numeric-character-references)
 //!
+//! [string]: crate::content::string
+//! [text]: crate::content::text
 //! [character_escape]: crate::construct::character_reference
 //! [decode_numeric]: crate::util::decode_numeric_character_reference
 //! [character_reference_names]: crate::constant::CHARACTER_REFERENCE_NAMES
diff --git a/src/construct/code_fenced.rs b/src/construct/code_fenced.rs
index 2068a62..a440d40 100644
--- a/src/construct/code_fenced.rs
+++ b/src/construct/code_fenced.rs
@@ -1,4 +1,4 @@
-//! Code (fenced) is a construct that occurs in the flow content type.
+//! Code (fenced) is a construct that occurs in the [flow][] content type.
 //!
 //! It forms with the following BNF:
 //!
@@ -63,10 +63,10 @@
 //! </code></pre>
 //! ```
 //!
-//! The `info` and `meta` parts are interpreted as the string content type.
+//! The `info` and `meta` parts are interpreted as the [string][] content type.
 //! That means that character escapes and character reference are allowed.
 //!
-//! In markdown, it is also possible to use code (text) in the text content
+//! In markdown, it is also possible to use code (text) in the [text][] content
 //! type.
 //! It is also possible to create code with the
 //! [code (indented)][code-indented] construct.
@@ -79,11 +79,14 @@
 //! *   [`code-fenced.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/code-fenced.js)
 //! *   [*§ 4.5 Fenced code blocks* in `CommonMark`](https://spec.commonmark.org/0.30/#fenced-code-blocks)
 //!
+//! [flow]: crate::content::flow
+//! [string]: crate::content::string
+//! [text]: crate::content::text
 //! [code-indented]: crate::construct::code_indented
 //! [html-pre]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-pre-element
 //! [html-code]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element
 //!
-//! <!-- To do: link `flow`, `text`, `code_text`, `string` -->
+//! <!-- To do: link `code_text` -->
 
 use crate::constant::{CODE_FENCED_SEQUENCE_SIZE_MIN, TAB_SIZE};
 use crate::construct::partial_whitespace::start as whitespace;
diff --git a/src/construct/code_indented.rs b/src/construct/code_indented.rs
index 6bf089b..936f174 100644
--- a/src/construct/code_indented.rs
+++ b/src/construct/code_indented.rs
@@ -1,4 +1,4 @@
-//! Code (indented) is a construct that occurs in the flow content type.
+//! Code (indented) is a construct that occurs in the [flow][] content type.
 //!
 //! It forms with the following BNF:
 //!
@@ -31,11 +31,12 @@
 //! *   [`code-indented.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/code-indented.js)
 //! *   [*§ 4.4 Indented code blocks* in `CommonMark`](https://spec.commonmark.org/0.30/#indented-code-blocks)
 //!
+//! [flow]: crate::content::flow
 //! [code-fenced]: crate::construct::code_fenced
 //! [html-pre]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-pre-element
 //! [html-code]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-code-element
 //!
-//! <!-- To do: link `flow`, `code_text` -->
+//! <!-- To do: link `code_text` -->
 
 use crate::constant::TAB_SIZE;
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
diff --git a/src/construct/heading_atx.rs b/src/construct/heading_atx.rs
index b3aef1b..3be8c99 100644
--- a/src/construct/heading_atx.rs
+++ b/src/construct/heading_atx.rs
@@ -1,4 +1,4 @@
-//! Heading (atx) is a construct that occurs in the flow content type.
+//! Heading (atx) is a construct that occurs in the [flow] content type.
 //!
 //! They’re formed with the following BNF:
 //!
@@ -38,11 +38,12 @@
 //! *   [`heading-atx.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/heading-atx.js)
 //! *   [*§ 4.2 ATX headings* in `CommonMark`](https://spec.commonmark.org/0.30/#atx-headings)
 //!
+//! [flow]: crate::content::flow
 //! [html]: https://html.spec.whatwg.org/multipage/sections.html#the-h1,-h2,-h3,-h4,-h5,-and-h6-elements
 //! [wiki-setext]: https://en.wikipedia.org/wiki/Setext
 //! [atx]: http://www.aaronsw.com/2002/atx/
 //!
-//! <!-- To do: link `flow`, `setext` -->
+//! <!-- To do: link `setext` -->
 
 use crate::constant::HEADING_ATX_OPENING_FENCE_SIZE_MAX;
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
diff --git a/src/construct/html_flow.rs b/src/construct/html_flow.rs
index b7d5570..a1b686b 100644
--- a/src/construct/html_flow.rs
+++ b/src/construct/html_flow.rs
@@ -1,4 +1,4 @@
-//! HTML (flow) is a construct that occurs in the flow content type.
+//! HTML (flow) is a construct that occurs in the [flow][] content type.
 //!
 //! It forms with the following BNF:
 //!
@@ -80,11 +80,12 @@
 //! *   [`html-flow.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/html-flow.js)
 //! *   [*§ 4.6 HTML blocks* in `CommonMark`](https://spec.commonmark.org/0.30/#html-blocks)
 //!
+//! [flow]: crate::content::flow
 //! [html_raw_names]: crate::constant::HTML_RAW_NAMES
 //! [html_block_names]: crate::constant::HTML_BLOCK_NAMES
 //! [html-parsing]: https://html.spec.whatwg.org/multipage/parsing.html#parsing
 //!
-//! <!-- To do: link stuff -->
+//! <!-- To do: link html (text) -->
 
 use crate::constant::{HTML_BLOCK_NAMES, HTML_RAW_NAMES, HTML_RAW_SIZE_MAX};
 use crate::construct::{blank_line::start as blank_line, partial_whitespace::start as whitespace};
diff --git a/src/construct/partial_whitespace.rs b/src/construct/partial_whitespace.rs
index dd0d2b5..b8cf9a7 100644
--- a/src/construct/partial_whitespace.rs
+++ b/src/construct/partial_whitespace.rs
@@ -12,8 +12,6 @@
 //! ## References
 //!
 //! *   [`micromark-factory-space/index.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-factory-space/dev/index.js)
-//!
-//! <!-- To do: link stuff -->
 
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
 
diff --git a/src/construct/thematic_break.rs b/src/construct/thematic_break.rs
index 15ebac7..7a4f71a 100644
--- a/src/construct/thematic_break.rs
+++ b/src/construct/thematic_break.rs
@@ -1,5 +1,5 @@
 //! Thematic breaks, sometimes called horizontal rules, are a construct that
-//! occurs in the flow content type.
+//! occurs in the [flow][] content type.
 //!
 //! They’re formed with the following BNF:
 //!
@@ -38,9 +38,10 @@
 //! *   [`thematic-break.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-core-commonmark/dev/lib/thematic-break.js)
 //! *   [*§ 4.1 Thematic breaks* in `CommonMark`](https://spec.commonmark.org/0.30/#thematic-breaks)
 //!
+//! [flow]: crate::content::flow
 //! [html]: https://html.spec.whatwg.org/multipage/grouping-content.html#the-hr-element
 //!
-//! <!-- To do: link `flow` -->
+//! <!-- To do: link `lists`, `setext heading` -->
 
 use crate::constant::THEMATIC_BREAK_MARKER_COUNT_MIN;
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};