From 43ba539936f4225f156c648585840b7c9b0866c2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= <vytas@rtfb.lt>
Date: Sat, 3 Sep 2016 13:16:41 +0300
Subject: [PATCH] Add some documentation to reference struct

---
 markdown.go | 41 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 39 insertions(+), 2 deletions(-)

diff --git a/markdown.go b/markdown.go
index f377a48..ff40230 100644
--- a/markdown.go
+++ b/markdown.go
@@ -535,13 +535,50 @@ func firstPass(p *parser, input []byte) []byte {
 //
 // are not yet supported.
 
-// References are parsed and stored in this struct.
+// reference holds all information necessary for a reference-style links or
+// footnotes.
+//
+// Consider this markdown with reference-style links:
+//
+//     [link][ref]
+//
+//     [ref]: /url/ "tooltip title"
+//
+// It will be ultimately converted to this HTML:
+//
+//     <p><a href=\"/url/\" title=\"title\">link</a></p>
+//
+// And a reference structure will be populated as follows:
+//
+//     p.refs["ref"] = &reference{
+//         link: "/url/",
+//         title: "tooltip title",
+//     }
+//
+// Alternatively, reference can contain an information about a footnote.
+// Consider this markdown:
+//
+//     Text needing a footnote.[^a]
+//
+//     [^a]: This is the note
+//
+// A reference structure will be populated as follows:
+//
+//     p.refs["a"] = &reference{
+//         link: "a",
+//         title: "This is the note",
+//         noteID: <some positive int>,
+//     }
+//
+// TODO: As you can see, it begs for splitting into two dedicated structures
+// for refs and for footnotes.
 type reference struct {
 	link     []byte
 	title    []byte
 	noteID   int // 0 if not a footnote ref
 	hasBlock bool
-	text     []byte
+
+	text []byte // only gets populated by refOverride feature with Reference.Text
 }
 
 func (r *reference) String() string {