diff --git a/README.md b/README.md
index 84d81f6..2e0db35 100644
--- a/README.md
+++ b/README.md
@@ -52,8 +52,9 @@ Potential drawbacks:
   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 @@ Usage
 For the most sensible markdown processing, it is as simple as getting your input
 into a byte slice and calling:
 
-    output := blackfriday.Run(input)
+```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:
 
-    output := blackfriday.Run(input, blackfriday.WithNoExtensions())
+```go
+output := blackfriday.Run(input, blackfriday.WithNoExtensions())
+```
 
 ### Sanitize untrusted content
 
@@ -77,7 +82,7 @@ through HTML sanitizer such as [Bluemonday][5].
 
 Here's an example of simple usage of Blackfriday together with Bluemonday:
 
-``` go
+```go
 import (
     "github.com/microcosm-cc/bluemonday"
     "github.com/russross/blackfriday"
@@ -179,7 +184,7 @@ implements the following extensions:
     and supply a language (to make syntax highlighting simple). Just
     mark it like this:
 
-        ``` go
+        ```go
         func getTrue() bool {
             return true
         }
diff --git a/doc.go b/doc.go
index 6cf29ce..5b3fa98 100644
--- a/doc.go
+++ b/doc.go
@@ -4,8 +4,8 @@
 // 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
diff --git a/markdown.go b/markdown.go
index d3756b5..ff61cb0 100644
--- a/markdown.go
+++ b/markdown.go
@@ -19,7 +19,8 @@ import (
 // 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
@@ -167,9 +168,8 @@ type Renderer interface {
 // 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 @@ func Run(input []byte, opts ...Option) []byte {
 // 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