Working on documentation
diff --git a/pkgs/markdown/CHANGELOG.md b/pkgs/markdown/CHANGELOG.md index 5d6b84a..d8e2fc8 100644 --- a/pkgs/markdown/CHANGELOG.md +++ b/pkgs/markdown/CHANGELOG.md
@@ -19,6 +19,7 @@ subclasses. * New public members for ListSyntax: `blocksInList` and `determineBlockItems()`, meant for use in subclasses. +* Improve public docs (better, and more of them). ## 0.8.0
diff --git a/pkgs/markdown/lib/markdown.dart b/pkgs/markdown/lib/markdown.dart index 78e5e7c..0cdaab0 100644 --- a/pkgs/markdown/lib/markdown.dart +++ b/pkgs/markdown/lib/markdown.dart
@@ -2,7 +2,7 @@ // for details. All rights reserved. Use of this source code is governed by a // BSD-style license that can be found in the LICENSE file. -/// Parses text in a markdown-like format and renders to HTML. +/// Parses text in a Markdown-like format and renders to HTML. library markdown; export 'src/ast.dart';
diff --git a/pkgs/markdown/lib/src/ast.dart b/pkgs/markdown/lib/src/ast.dart index 00f4ff3..5cc3e7c 100644 --- a/pkgs/markdown/lib/src/ast.dart +++ b/pkgs/markdown/lib/src/ast.dart
@@ -6,8 +6,9 @@ typedef Node Resolver(String name); -/// Base class for any AST item. Roughly corresponds to Node in the DOM. Will -/// be either an Element or Text. +/// Base class for any AST item. +/// +/// Roughly corresponds to Node in the DOM. Will be either an Element or Text. abstract class Node { void accept(NodeVisitor visitor); } @@ -19,20 +20,25 @@ final Map<String, String> attributes; String generatedId; + /// Instantiates a [tag] Element with [children]. Element(this.tag, this.children) : attributes = <String, String>{}; + /// Instantiates an empty, self-closing [tag] Element. Element.empty(this.tag) : children = null, attributes = {}; + /// Instantiates a [tag] Element with no [children]. Element.withTag(this.tag) : children = [], attributes = {}; + /// Instantiates a [tag] Element with a single Text child. Element.text(this.tag, String text) : children = [new Text(text)], attributes = {}; + /// Whether this element is self-closing. bool get isEmpty => children == null; void accept(NodeVisitor visitor) { @@ -51,17 +57,22 @@ void accept(NodeVisitor visitor) => visitor.visitText(this); } -/// Visitor pattern for the AST. Renderers or other AST transformers should -/// implement this. +/// Visitor pattern for the AST. +/// +/// Renderers or other AST transformers should implement this. abstract class NodeVisitor { /// Called when a Text node has been reached. void visitText(Text text); /// Called when an Element has been reached, before its children have been - /// visited. Return `false` to skip its children. + /// visited. + /// + /// Returns `false` to skip its children. bool visitElementBefore(Element element); /// Called when an Element has been reached, after its children have been - /// visited. Will not be called if [visitElementBefore] returns `false`. + /// visited. + /// + /// Will not be called if [visitElementBefore] returns `false`. void visitElementAfter(Element element); }
diff --git a/pkgs/markdown/lib/src/block_parser.dart b/pkgs/markdown/lib/src/block_parser.dart index 6a1d720..549fc3d 100644 --- a/pkgs/markdown/lib/src/block_parser.dart +++ b/pkgs/markdown/lib/src/block_parser.dart
@@ -48,15 +48,17 @@ final _olPattern = new RegExp(r'^[ ]{0,3}\d+\.[ \t]+(.*)$'); /// Maintains the internal state needed to parse a series of lines into blocks -/// of markdown suitable for further inline parsing. +/// of Markdown suitable for further inline parsing. class BlockParser { final List<String> lines; - /// The markdown document this parser is parsing. + /// The Markdown document this parser is parsing. final Document document; - /// The enabled block syntaxes. To turn a series of lines into blocks, each of - /// these will be tried in turn. Order matters here. + /// The enabled block syntaxes. + /// + /// To turn a series of lines into blocks, each of these will be tried in + /// turn. Order matters here. final List<BlockSyntax> blockSyntaxes = []; /// Index of the current line. @@ -309,7 +311,7 @@ /// Parses preformatted code blocks between two ~~~ or ``` sequences. /// -/// See [Pandoc's documentation](http://johnmacfarlane.net/pandoc/demo/example9/pandocs-markdown.html). +/// See [Pandoc's documentation](http://pandoc.org/README.html#fenced-code-blocks). class FencedCodeBlockSyntax extends BlockSyntax { RegExp get pattern => _codePattern;
diff --git a/pkgs/markdown/lib/src/document.dart b/pkgs/markdown/lib/src/document.dart index fc5fa82..2b9216d 100644 --- a/pkgs/markdown/lib/src/document.dart +++ b/pkgs/markdown/lib/src/document.dart
@@ -29,6 +29,8 @@ ..addAll(extensionSet.inlineSyntaxes); } + /// Parses [lines] for reference links, adding them to [refLinks] and + /// replaces their source lines with blank lines. parseRefLinks(List<String> lines) { // This is a hideous regex. It matches: // [id]: http:foo.com "some title" @@ -70,7 +72,7 @@ } } - /// Parse the given [lines] of markdown to a series of AST nodes. + /// Parses the given [lines] of Markdown to a series of AST nodes. List<Node> parseLines(List<String> lines) { var parser = new BlockParser(lines, this); @@ -88,10 +90,7 @@ return blocks; } - /// Takes a string of raw text and processes all inline markdown tags, - /// returning a list of AST nodes. For example, given ``"*this **is** a* - /// `markdown`"``, returns: - /// `<em>this <strong>is</strong> a</em> <code>markdown</code>`. + /// Parses the given inline Markdown [text] to a series of AST nodes. List<Node> parseInline(String text) => new InlineParser(text, this).parse(); }
diff --git a/pkgs/markdown/lib/src/html_renderer.dart b/pkgs/markdown/lib/src/html_renderer.dart index aa17d5e..d9f8111 100644 --- a/pkgs/markdown/lib/src/html_renderer.dart +++ b/pkgs/markdown/lib/src/html_renderer.dart
@@ -11,7 +11,7 @@ import 'extension_set.dart'; import 'inline_parser.dart'; -/// Converts the given string of markdown to HTML. +/// Converts the given string of Markdown to HTML. String markdownToHtml(String markdown, {Iterable<BlockSyntax> blockSyntaxes, Iterable<InlineSyntax> inlineSyntaxes, @@ -35,6 +35,7 @@ return renderToHtml(document.parseLines(lines)) + '\n'; } +/// Renders [nodes] to HTML. String renderToHtml(List<Node> nodes) => new HtmlRenderer().render(nodes); /// Translates a parsed AST to HTML.
diff --git a/pkgs/markdown/lib/src/inline_parser.dart b/pkgs/markdown/lib/src/inline_parser.dart index 77a947c..afa9d37 100644 --- a/pkgs/markdown/lib/src/inline_parser.dart +++ b/pkgs/markdown/lib/src/inline_parser.dart
@@ -9,17 +9,14 @@ import 'util.dart'; /// Maintains the internal state needed to parse inline span elements in -/// markdown. +/// Markdown. class InlineParser { static final List<InlineSyntax> _defaultSyntaxes = <InlineSyntax>[ - // This first regexp matches plain text to accelerate parsing. It must - // be written so that it does not match any prefix of any following - // syntax. Most markdown is plain text, so it is faster to match one - // regexp per 'word' rather than fail to match all the following regexps - // at each non-syntax character position. It is much more important - // that the regexp is fast than complete (for example, adding grouping - // is likely to slow the regexp down enough to negate its benefit). - // Since it is purely for optimization, it can be removed for debugging. + // This first RegExp matches plain text to accelerate parsing. It's written + // so that it does not match any prefix of any following syntaxes. Most + // Markdown is plain text, so it's faster to match one RegExp per 'word' + // rather than fail to match all the following RegExps at each non-syntax + // character position. // TODO(amouravski): this regex will glom up any custom syntaxes unless // they're at the beginning. @@ -58,10 +55,10 @@ // We will add the LinkSyntax once we know about the specific link resolver. ]; - /// The string of markdown being parsed. + /// The string of Markdown being parsed. final String source; - /// The markdown document this parser is parsing. + /// The Markdown document this parser is parsing. final Document document; final List<InlineSyntax> syntaxes = <InlineSyntax>[]; @@ -159,13 +156,13 @@ } } -/// Represents one kind of markdown tag that can be parsed. +/// Represents one kind of Markdown tag that can be parsed. abstract class InlineSyntax { final RegExp pattern; InlineSyntax(String pattern) : pattern = new RegExp(pattern, multiLine: true); - /// Try to match at the parser's current position. + /// Tries to match at the parser's current position. /// /// Returns whether or not the pattern successfully matched. bool tryMatch(InlineParser parser) { @@ -181,6 +178,10 @@ return false; } + /// Processes [match], adding nodes to [parser] and possibly advancing + /// [parser]. + /// + /// Returns whether the caller should advance [parser] by `match[0].length`. bool onMatch(InlineParser parser, Match match); } @@ -222,7 +223,7 @@ /// [CommonMark 0.22](http://spec.commonmark.org/0.22/#raw-html). /// /// This is not actually a good definition (nor CommonMark's) of an HTML tag, -/// but it is fast. It will leave text like <a href='hi"> alone, which is +/// but it is fast. It will leave text like `<a href='hi">` alone, which is /// incorrect. /// /// TODO(srawlins): improve accuracy while ensuring performance, once @@ -272,9 +273,11 @@ class LinkSyntax extends TagSyntax { final Resolver linkResolver; - /// The regex for the end of a link needs to handle both reference-style and - /// inline-style links as well as optional titles for inline links. To make that - /// a bit more palatable, this breaks it into pieces. + /// The regex for the end of a link. + /// + /// This handles both reference-style and inline-style links as well as + /// optional titles for inline links. To make that a bit more palatable, this + /// breaks it into pieces. static get linkPattern { var refLink = r'\[([^\]]*)\]'; // `[id]` reflink id. var title = r'(?:\s*"([^"]+)"|)'; // Optional title in quotes. @@ -436,8 +439,9 @@ } } -/// Keeps track of a currently open tag while it is being parsed. The parser -/// maintains a stack of these so it can handle nested tags. +/// Keeps track of a currently open tag while it is being parsed. +/// +/// The parser maintains a stack of these so it can handle nested tags. class TagState { /// The point in the original source where this tag started. final int startPos; @@ -467,6 +471,7 @@ } /// Pops this tag off the stack, completes it, and adds it to the output. + /// /// Will discard any unmatched tags that happen to be above it on the stack. /// If this is the last node in the stack, returns its children. List<Node> close(InlineParser parser, Match endMatch) {