From e0485409fca79af0b47af15ebdba7a3df5c1d3d2 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Wed, 12 Oct 2022 10:44:33 +0200 Subject: Refactor to improve some module docs --- src/construct/autolink.rs | 2 +- src/construct/blank_line.rs | 6 +++--- src/construct/block_quote.rs | 2 +- src/construct/character_escape.rs | 7 +++---- src/construct/gfm_footnote_definition.rs | 4 ++-- src/construct/heading_setext.rs | 2 +- src/construct/html_flow.rs | 6 +++--- src/construct/html_text.rs | 2 +- src/construct/list_item.rs | 4 ++-- src/construct/mdx_esm.rs | 3 ++- src/construct/partial_bom.rs | 1 + src/construct/raw_text.rs | 7 ++++--- 12 files changed, 24 insertions(+), 22 deletions(-) (limited to 'src/construct') 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 @@ //! (see [construct][crate::construct] for character groups): //! //! ```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 -//!
This is a div but *this* is not emphasis.
+//!
This is code but this is not *emphasis*.
//! //!
//! -//! This is a paragraph in a `div` and *this* is emphasis. +//! This is a paragraph in a `div` and with `code` and *emphasis*. //! //!
//! ``` 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}; -- cgit