From d5487615af9351eb17f94cae5106cdc0d03bad11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sat, 29 Jul 2017 11:59:03 +0300 Subject: [PATCH 1/2] Several small documentation fixes --- README.md | 9 +++++++-- doc.go | 4 ++-- html.go | 4 ++-- markdown.go | 11 ++++++----- node.go | 4 ++-- 5 files changed, 19 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 84d81f6..56bd09f 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: +``` 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 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/html.go b/html.go index f1a60de..620ed17 100644 --- a/html.go +++ b/html.go @@ -482,8 +482,8 @@ func (r *HTMLRenderer) outHRTag(w io.Writer) { } // 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 diff --git a/markdown.go b/markdown.go index d3756b5..5e04f68 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 @@ -142,7 +143,7 @@ var blockTags = map[string]struct{}{ 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 @@ 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 diff --git a/node.go b/node.go index 51b9e8c..4f845ed 100644 --- a/node.go +++ b/node.go @@ -272,8 +272,8 @@ const ( ) // 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 From 19913a1b7639bcbbe13e7d073f08c6bb098d8254 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vytautas=20=C5=A0altenis?= Date: Sun, 30 Jul 2017 19:50:50 +0300 Subject: [PATCH 2/2] Address feedback --- README.md | 12 ++++++------ html.go | 4 ++-- markdown.go | 2 +- node.go | 4 ++-- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 56bd09f..2e0db35 100644 --- a/README.md +++ b/README.md @@ -62,16 +62,16 @@ Usage 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) +```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()) +```go +output := blackfriday.Run(input, blackfriday.WithNoExtensions()) ``` ### Sanitize untrusted content @@ -82,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" @@ -184,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/html.go b/html.go index 620ed17..f1a60de 100644 --- a/html.go +++ b/html.go @@ -482,8 +482,8 @@ func (r *HTMLRenderer) outHRTag(w io.Writer) { } // 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 diff --git a/markdown.go b/markdown.go index 5e04f68..ff61cb0 100644 --- a/markdown.go +++ b/markdown.go @@ -143,7 +143,7 @@ var blockTags = map[string]struct{}{ 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 diff --git a/node.go b/node.go index 4f845ed..51b9e8c 100644 --- a/node.go +++ b/node.go @@ -272,8 +272,8 @@ const ( ) // 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