@@ -52,8 +52,9 @@ * Our benchmarks show v2 to be slightly slower than v1. Currently in the
   ballpark of around 15%.
 * API breakage. If you can't afford modifying your code to adhere to the new API
   and don't care too much about the new features, v2 is probably not for you.
-* Some bug fixes are trailing behind and still need to be forward-ported to v2.
-  See issue #348 for tracking.
+* Several bug fixes are trailing behind and still need to be forward-ported to
+  v2. See issue [#348](https://github.com/russross/blackfriday/issues/348) for
+  tracking.
 
 Usage
 -----
@@ -61,13 +62,17 @@ 
 For the most sensible markdown processing, it is as simple as getting your input
 into a byte slice and calling:
 
+``` go
     output := blackfriday.Run(input)
+```
 
 Your input will be parsed and the output rendered with a set of most popular
 extensions enabled. If you want the most basic feature set, corresponding with
 the bare Markdown specification, use:
 
+``` go
     output := blackfriday.Run(input, blackfriday.WithNoExtensions())
+```
 
 ### Sanitize untrusted content
 

@@ -4,8 +4,8 @@ // It translates plain text with simple formatting rules into an AST, which can
 // then be further processed to HTML (provided by Blackfriday itself) or other
 // formats (provided by the community).
 //
-// The simplest way to invoke Blackfriday is to call the Markdown function. It
-// will take a text input and produce a text output in HTML (or other format).
+// The simplest way to invoke Blackfriday is to call the Run function. It will
+// take a text input and produce a text output in HTML (or other format).
 //
 // A slightly more sophisticated way to use Blackfriday is to create a Markdown
 // processor and to call Parse, which returns a syntax tree for the input

@@ -482,8 +482,8 @@ }
 }
 
 // RenderNode is a default renderer of a single node of a syntax tree. For
-// block nodes it will be called twice: first time with entering=true, second
-// time with entering=false, so that it could know when it's working on an open
+// block nodes it will be called twice: first time with entering=True, second
+// time with entering=False, so that it could know when it's working on an open
 // tag and when on close. It writes the result to w.
 //
 // The return value is a way to tell the calling walker to adjust its walk

@@ -19,7 +19,8 @@ //
 // Markdown parsing and processing
 //
 
-// Version string of the package.
+// Version string of the package. Appears in the rendered document when
+// CompletePage flag is on.
 const Version = "2.0"
 
 // Extensions is a bitwise or'ed collection of enabled Blackfriday's
@@ -142,7 +143,7 @@ // for external implementations.
 type Renderer interface {
 	// RenderNode is the main rendering method. It will be called once for
 	// every leaf node and twice for every non-leaf node (first with
-	// entering=true, then with entering=false). The method should write its
+	// entering=True, then with entering=False). The method should write its
 	// rendition of the node to the supplied writer w.
 	RenderNode(w io.Writer, node *Node, entering bool) WalkStatus
 
@@ -167,9 +168,8 @@ // Callback functions for inline parsing. One such function is defined
 // for each character that triggers a response when parsing inline data.
 type inlineParser func(p *Markdown, data []byte, offset int) (int, *Node)
 
-// Markdown is a type that holds:
-// - extensions and the runtime state used by Parse,
-// - the renderer.
+// Markdown is a type that holds extensions and the runtime state used by
+// Parse, and the renderer. You can not use it directly, construct it with New.
 type Markdown struct {
 	renderer          Renderer
 	referenceOverride ReferenceOverrideFunc
@@ -399,6 +399,7 @@ // Parse is an entry point to the parsing part of Blackfriday. It takes an
 // input markdown document and produces a syntax tree for its contents. This
 // tree can then be rendered with a default or custom renderer, or
 // analyzed/transformed by the caller to whatever non-standard needs they have.
+// The return value is the root node of the syntax tree.
 func (p *Markdown) Parse(input []byte) *Node {
 	p.block(input)
 	// Walk the tree and finish up some of unfinished blocks

@@ -272,8 +272,8 @@ Terminate
 )
 
 // NodeVisitor is a callback to be called when traversing the syntax tree.
-// Called twice for every node: once with entering=true when the branch is
-// first visited, then with entering=false after all the children are done.
+// Called twice for every node: once with entering=True when the branch is
+// first visited, then with entering=False after all the children are done.
 type NodeVisitor func(node *Node, entering bool) WalkStatus
 
 // Walk is a convenience method that instantiates a walker and starts a