more doc tweaking

markdown.go

@@ -34,10 +34,11 @@ type Renderer interface {
 	RenderFooter(w io.Writer, ast ast.Node)
 }
 
-// Parse parsers a markdown document using provided parser or parser configured
-// with parser.CommonExtensions if parser is nil.
+// Parse parsers a markdown document using provided parser. If parser is nil,
+// we use parser configured with parser.CommonExtensions.
 //
-// It returns ast tree that can be converted to another format using a renderer.
+// It returns AST (abstract syntax tree) that can be converted to another
+// format using Render function.
 func Parse(markdown []byte, p *parser.Parser) ast.Node {
 	if p == nil {
 		p = parser.New()
@@ -47,7 +48,7 @@ func Parse(markdown []byte, p *parser.Parser) ast.Node {
 
 // Render uses renderer to convert parsed markdown document into a different format.
 //
-// To convert to HTML, use html.Renderer
+// To convert to HTML, pass html.Renderer
 func Render(doc ast.Node, renderer Renderer) []byte {
 	var buf bytes.Buffer
 	renderer.RenderHeader(&buf, doc)

parser/parser.go

@@ -100,13 +100,15 @@ type Parser struct {
 }
 
 // New creates a markdown parser with CommonExtensions.
+//
+// You can then call `doc := p.Parse(markdown)` to parse markdown document
+// and `markdown.Render(doc, renderer)` to convert it to another format with
+// a renderer.
 func New() *Parser {
 	return NewWithExtensions(CommonExtensions)
 }
 
 // NewWithExtensions creates a markdown parser with given extensions.
-// Before
-// for Run() to customize parser's behavior and the renderer.
 func NewWithExtensions(extension Extensions) *Parser {
 	p := Parser{
 		refs:       make(map[string]*reference),