From 912f91b2b35be6b0d05dd768d67599d76151bc5c Mon Sep 17 00:00:00 2001
From: Titus Wormer <tituswormer@gmail.com>
Date: Mon, 20 Jun 2022 11:58:48 +0200
Subject: Add docs to destination, label, title

---
 src/construct/partial_label.rs | 81 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 75 insertions(+), 6 deletions(-)

(limited to 'src/construct/partial_label.rs')

diff --git a/src/construct/partial_label.rs b/src/construct/partial_label.rs
index c772c56..f7ce8d7 100644
--- a/src/construct/partial_label.rs
+++ b/src/construct/partial_label.rs
@@ -1,9 +1,65 @@
+//! Label occurs in [definition][] and label end.
+//!
+//! They’re formed with the following BNF:
+//!
+//! ```bnf
+//! ; Restriction: maximum `999` codes allowed between brackets.
+//! ; Restriction: no blank lines.
+//! ; Restriction: at least 1 non-space and non-eol code must exist.
+//! label ::= '[' *( label_text | label_escape ) ']'
+//! label_text ::= code - '[' - '\\' - ']'
+//! label_escape ::= '\\' [ '[' | '\\' | ']' ]
+//! ```
+//!
+//! The maximum allowed size of the label, without the brackets, is `999`
+//! (inclusive), which is defined in
+//! [`LINK_REFERENCE_SIZE_MAX`][link_reference_size_max].
+//!
+//! Labels can contain line endings and whitespace, but they are not allowed to
+//! contain blank lines, and they must not be blank themselves.
+//!
+//! The label is interpreted as the [string][] content type.
+//! That means that character escapes and character reference are allowed.
+//!
+//! > 👉 **Note**: this label relates to, but is not, the initial “label” of
+//! > what is know as a reference in markdown:
+//! >
+//! > | Kind      | Link     | Image     |
+//! > | --------- | -------- | --------- |
+//! > | Shortcut  | `[x]`    | `![x]`    |
+//! > | Collapsed | `[x][]`  | `![x][]`  |
+//! > | Full      | `[x][y]` | `![x][y]` |
+//! >
+//! > The 6 above things are references, in the three kinds they come in, as
+//! > links and images.
+//! > The label that this module focusses on is only the thing that contains
+//! > `y`.
+//! >
+//! > The thing that contains `x` is not a single thing when parsing markdown,
+//! > but instead constists of an opening (label start (image) or label start
+//! > (link)) and a closing (label end), so as to allow further phrasing such
+//! > as code (text) or attention.
+//!
+//! ## References
+//!
+//! *   [`micromark-factory-label/index.js` in `micromark`](https://github.com/micromark/micromark/blob/main/packages/micromark-factory-label/dev/index.js)
+//!
+//! [definition]: crate::construct::definition
+//! [string]: crate::content::string
+//! [link_reference_size_max]: crate::constant::LINK_REFERENCE_SIZE_MAX
+//!
+//! <!-- To do: link label end, label starts. -->
+
 // To do: pass token types in.
 
 use crate::constant::LINK_REFERENCE_SIZE_MAX;
 use crate::tokenizer::{Code, State, StateFnResult, TokenType, Tokenizer};
 
-/// To do.
+/// Before a label.
+///
+/// ```markdown
+/// |[a]
+/// ```
 pub fn start(tokenizer: &mut Tokenizer, code: Code) -> StateFnResult {
     match code {
         Code::Char('[') => {
@@ -14,12 +70,16 @@ pub fn start(tokenizer: &mut Tokenizer, code: Code) -> StateFnResult {
             tokenizer.enter(TokenType::DefinitionLabelData);
             (State::Fn(Box::new(|t, c| at_break(t, c, false, 0))), None)
         }
-        // To do: allow?
-        _ => unreachable!("expected `[` at start of label"),
+        _ => (State::Nok, None),
     }
 }
 
-/// To do.
+/// In a label, at something.
+///
+/// ```markdown
+/// [|a]
+/// [a|]
+/// ```
 fn at_break(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> StateFnResult {
     match code {
         Code::None | Code::Char('[') => (State::Nok, None),
@@ -37,6 +97,7 @@ fn at_break(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> S
             tokenizer.enter(TokenType::LineEnding);
             tokenizer.consume(code);
             tokenizer.exit(TokenType::LineEnding);
+            // To do: limit blank lines.
             (
                 State::Fn(Box::new(move |t, c| at_break(t, c, data, size))),
                 None,
@@ -50,7 +111,11 @@ fn at_break(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> S
     }
 }
 
-/// To do.
+/// In a label, in text.
+///
+/// ```markdown
+/// [a|b]
+/// ```
 fn label(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> StateFnResult {
     match code {
         Code::None | Code::CarriageReturnLineFeed | Code::Char('\r' | '\n' | '[' | ']') => {
@@ -85,7 +150,11 @@ fn label(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> Stat
     }
 }
 
-/// To do.
+/// After `\` in a label.
+///
+/// ```markdown
+/// [a\|[b]
+/// ```
 fn escape(tokenizer: &mut Tokenizer, code: Code, data: bool, size: usize) -> StateFnResult {
     match code {
         Code::Char('[' | '\\' | ']') => {
-- 
cgit