Merge pull request dart-lang/markdown#69 from srawlins/more-docs
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) {
