Add docs on constructs, bnf

3 files changed, 57 insertions, 1 deletions

diff --git a/readme.md b/readme.md
index 8335644..a735a36 100644
--- a/readme.md
+++ b/readme.md
@@ -69,7 +69,6 @@ cargo doc --document-private-items
 ### Small things
 
 - [ ] (3) Fix deep subtokenization
-- [ ] (1) Add docs on bnf
 - [ ] (1) Add docs to subtokenize
 - [ ] (1) Add module docs to content
 - [ ] (1) Add module docs to parser
@@ -165,6 +164,7 @@ cargo doc --document-private-items
 - [x] (3) Encode urls
 - [x] (1) Optionally remove dangerous protocols when compiling
 - [x] (1) Add docs to html (text)
+- [x] (1) Add docs on bnf
 
 ### Extensions
 
diff --git a/src/construct/autolink.rs b/src/construct/autolink.rs
index c190d40..2682878 100644
--- a/src/construct/autolink.rs
+++ b/src/construct/autolink.rs
@@ -74,6 +74,8 @@
 //! [autolink_scheme_size_max]: crate::constant::AUTOLINK_SCHEME_SIZE_MAX
 //! [autolink_domain_size_max]: crate::constant::AUTOLINK_DOMAIN_SIZE_MAX
 //! [html-a]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-a-element
+//!
+//! <!-- To do: add explanation of sanitation. -->
 
 use crate::constant::{AUTOLINK_DOMAIN_SIZE_MAX, AUTOLINK_SCHEME_SIZE_MAX};
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
diff --git a/src/construct/mod.rs b/src/construct/mod.rs
index 31d9f6d..d2203d2 100644
--- a/src/construct/mod.rs
+++ b/src/construct/mod.rs
@@ -1,4 +1,58 @@
 //! Constructs found in markdown.
+//!
+//! There are several *things* found when parsing markdown, such as, say, a
+//! thematic break.
+//! These things are called constructs here.
+//! Sometimes, there are several constructs that result in an equivalent thing.
+//! For example, [code (fenced)][code_fenced] and
+//! [code (indented)][code_indented] are considered different constructs
+//!
+//! <!-- To do: can these rest things be made into constructs? -->
+//!
+//! Content types also have a *rest* thing: after all character escapes and
+//! character references are parsed, there’s something left.
+//! This remainder is, currently, not called a constructs.
+//!
+//! The following constructs are found in markdown:
+//!
+//! *   attention (strong, emphasis) (text)
+//! *   [autolink][autolink]
+//! *   [blank line][blank_line]
+//! *   block quote
+//! *   [character escape][character_escape]
+//! *   [character reference][character_reference]
+//! *   [code (fenced)][code_fenced]
+//! *   [code (indented)][code_indented]
+//! *   code (text)
+//! *   content
+//! *   definition
+//! *   hard break escape
+//! *   [heading (atx)][heading_atx]
+//! *   heading (setext)
+//! *   [html (flow)][html_flow]
+//! *   [html (text)][html_text]
+//! *   label end
+//! *   label start (image)
+//! *   label start (link)
+//! *   list
+//! *   paragraph
+//! *   [thematic break][thematic_break]
+//!
+//! Each construct maintained here is explained with a BNF diagram.
+//! For example, the docs for [character escape][character_escape] contain:
+//!
+//! ```bnf
+//! character_escape ::= '\\' ascii_punctuation
+//! ```
+//!
+//! Such diagrams are considered to be *non-normative*.
+//! That is to say, they form illustrative, imperfect, but useful, examples.
+//! The code, in Rust, is considered to be normative.
+//!
+//! They also contain references to character as defined by [char][], so for
+//! example `ascii_punctuation` refers to
+//! [`char::is_ascii_punctuation`][char::is_ascii_punctuation].
+
 
 pub mod autolink;
 pub mod blank_line;