Improvements to documentation (dart-lang/markdown#397)

Documentation is added to the library statement that provides some
introduction of the library guiding a user wanting to extend the syntax.

Other minor changes:

- Add `doc/` to `.gitignore`
- Fix a link to Github Flavor that raised an unresolved doc reference in
  dartdoc.
- Ensure all references to the language are capitalised (Markdown) and
  references to the library are lowercased (markdown)
- Fix a couple of references to unexisting elements (probably leftovers
  of earlier refactorings)
- Add new line to end of `.gitignore`

pkgs/markdown/.gitignore

diff --git a/pkgs/markdown/.gitignore b/pkgs/markdown/.gitignore
index 2afa93d..6ff0be3 100644
--- a/pkgs/markdown/.gitignore
+++ b/pkgs/markdown/.gitignore
@@ -2,3 +2,4 @@
 .packages
 .pub
 pubspec.lock
+doc/

pkgs/markdown/lib/markdown.dart

diff --git a/pkgs/markdown/lib/markdown.dart b/pkgs/markdown/lib/markdown.dart
index 06141cd..3af6c6c 100644
--- a/pkgs/markdown/lib/markdown.dart
+++ b/pkgs/markdown/lib/markdown.dart
@@ -2,7 +2,36 @@
 // 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 building an
+/// [AST tree](https://en.wikipedia.org/wiki/Abstract_syntax_tree)
+/// that can then be rendered to HTML.
+///
+/// If you are only interested in rendering Markdown to HTML please refer
+/// to the [README](../index.html) which explains the use of [markdownToHtml()].
+///
+/// The main entrypoint to the library is the [Document] which encapsulates the
+/// parsing process converting a Markdown text into a tree of [Node] (`List<Node>`).
+///
+/// Two main parsing mechanics are used:
+///
+/// - Blocks, representing top level elements like: headers, paragraphs, blockquotes,
+///   code blocks, ... implemented via [BlockSyntax] subclasses.
+/// - Inlines, representing chunks of text within a block with special meaning, like:
+///   links, emphasis, inlined code, ... implemented via [InlineSyntax] subclasses.
+///
+/// Looking closely at [Document.new()] a few other concepts merit a mention:
+///
+/// - [ExtensionSet] that provide configurations for common Markdown flavors
+/// - [Resolver] which aid in resolving links and images
+///
+/// If you are looking at extending the library to support custom formatting
+/// what you may want is to:
+///
+/// - Implement your own [InlineSyntax] subclasses
+/// - Implement your own [BlockSyntax] subclasses
+/// - Instruct the library to use those by:
+///   - Creating a new [ExtensionSet] from one of the existing flavors adding your syntaxes
+///   - Passing your syntaxes to [Document] or [markdownToHtml()] as parameters.
 library markdown;
 
 import 'src/version.dart';

pkgs/markdown/lib/src/extension_set.dart

diff --git a/pkgs/markdown/lib/src/extension_set.dart b/pkgs/markdown/lib/src/extension_set.dart
index 29fac31..9c8b823 100644
--- a/pkgs/markdown/lib/src/extension_set.dart
+++ b/pkgs/markdown/lib/src/extension_set.dart
@@ -60,10 +60,8 @@
     ),
   );
 
-  /// The [gitHubFlavored] extension set is close to compliance with the [GitHub
-  /// flavored Markdown spec].
-  ///
-  /// [GitHub flavored Markdown]: https://github.github.com/gfm/
+  /// The [gitHubFlavored] extension set is close to compliance with the
+  /// [GitHub flavored Markdown spec](https://github.github.com/gfm/).
   static final ExtensionSet gitHubFlavored = ExtensionSet(
     List<BlockSyntax>.unmodifiable(
       <BlockSyntax>[

pkgs/markdown/lib/src/inline_parser.dart

diff --git a/pkgs/markdown/lib/src/inline_parser.dart b/pkgs/markdown/lib/src/inline_parser.dart
index f7df299..e1f4a43 100644
--- a/pkgs/markdown/lib/src/inline_parser.dart
+++ b/pkgs/markdown/lib/src/inline_parser.dart
@@ -109,7 +109,7 @@
         continue;
       }
 
-      // See if the current text matches any defined markdown syntax.
+      // See if the current text matches any defined Markdown syntax.
       if (syntaxes.any((syntax) => syntax.tryMatch(this))) continue;
 
       // If we got here, it's just text.
@@ -319,12 +319,12 @@
     start = pos;
   }
 
-  /// Add [node] to the last [TagState] on the stack.
+  /// Add [node] to the current tree.
   void addNode(Node node) {
     _tree.add(node);
   }
 
-  /// Push [state] onto the stack of [TagState]s.
+  /// Push [delimiter] onto the stack of [Delimiter]s.
   void _pushDelimiter(Delimiter delimiter) => _delimiterStack.add(delimiter);
 
   bool get isDone => pos == source.length;
@@ -889,8 +889,7 @@
 
   /// Create a new [TagSyntax] which matches text on [pattern].
   ///
-  /// If [end] is passed, it is used as the pattern which denotes the end of
-  /// matching text. Otherwise, [pattern] is used. If [requiresDelimiterRun] is
+  /// The [pattern] is used to find the matching text. If [requiresDelimiterRun] is
   /// passed, this syntax parses according to the same nesting rules as
   /// emphasis delimiters.  If [startCharacter] is passed, it is used as a
   /// pre-matching check which is faster than matching against [pattern].