[SQUASH] Doc update

Author: Ambrevar

doc.go

@@ -4,14 +4,14 @@
 // 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 one of Markdown*
-// functions. 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 Markdown 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 call Parse, which
-// returns a syntax tree for the input document. You can use that to write your
-// own renderer or, for example, to leverage Blackfriday's parsing for content
-// extraction from markdown documents.
+// A slightly more sophisticated way to use Blackfriday is to create a Processor
+// and to call Parse, which returns a syntax tree for the input document. You
+// can leverage Blackfriday's parsing for content extraction from markdown
+// documents. You can assign a custom renderer and set various options to the
+// Processor.
 //
 // If you're interested in calling Blackfriday from command line, see
 // https://github.com/russross/blackfriday-tool.

markdown.go

@@ -156,8 +156,9 @@ type Renderer interface {
 // for each character that triggers a response when parsing inline data.
 type inlineParser func(p *Processor, data []byte, offset int) (int, *Node)
 
-// Processor holds runtime state used by the parser.
-// This is constructed by the Markdown function.
+// Processor holds:
+// - extensions and the runtime state used by Parse,
+// - the renderer.
 type Processor struct {
 	renderer          Renderer
 	referenceOverride ReferenceOverrideFunc
@@ -254,8 +255,8 @@ type Reference struct {
 // See the documentation in Options for more details on use-case.
 type ReferenceOverrideFunc func(reference string) (ref *Reference, overridden bool)
 
-// NewProcessor constructs a Parser. You can use the same With* functions as for
-// Markdown() to customize parser's behavior.
+// NewProcessor constructs a Processor. You can use the same With* functions as
+// for Markdown() to customize parser's behavior.
 func NewProcessor(opts ...Option) *Processor {
 	var p Processor
 	for _, opt := range opts {