diff --git a/example/call_parser.dart b/example/call_parser.dart
index 85325e4..fc6b33c 100644
--- a/example/call_parser.dart
+++ b/example/call_parser.dart
@@ -10,11 +10,9 @@
     warningsAsErrors: true,
     inputFile: 'memory');
 
-/**
- * Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
- * CSS will allow any property/value pairs regardless of validity; all of our
- * tests (by default) will ensure that the CSS is really valid.
- */
+/// Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
+/// CSS will allow any property/value pairs regardless of validity; all of our
+/// tests (by default) will ensure that the CSS is really valid.
 StyleSheet parseCss(String cssInput,
     {List<css.Message> errors, css.PreprocessorOptions opts}) {
   return css.parse(cssInput,
diff --git a/lib/parser.dart b/lib/parser.dart
index d0b8aea..bd750d9 100644
--- a/lib/parser.dart
+++ b/lib/parser.dart
@@ -29,7 +29,7 @@
   disjunction,
 }
 
-/** Used for parser lookup ahead (used for nested selectors Less support). */
+/// Used for parser lookup ahead (used for nested selectors Less support).
 class ParserState extends TokenizerState {
   final Token peekToken;
   final Token previousToken;
@@ -49,11 +49,11 @@
   messages = new Messages(options: options, printHandler: errors.add);
 }
 
-/** CSS checked mode enabled. */
+/// CSS checked mode enabled.
 bool get isChecked => messages.options.checked;
 
 // TODO(terry): Remove nested name parameter.
-/** Parse and analyze the CSS file. */
+/// Parse and analyze the CSS file.
 StyleSheet compile(input,
     {List<Message> errors,
     PreprocessorOptions options,
@@ -82,18 +82,16 @@
   return tree;
 }
 
-/** Analyze the CSS file. */
+/// Analyze the CSS file.
 void analyze(List<StyleSheet> styleSheets,
     {List<Message> errors, PreprocessorOptions options}) {
   _createMessages(errors: errors, options: options);
   new Analyzer(styleSheets, messages).run();
 }
 
-/**
- * Parse the [input] CSS stylesheet into a tree. The [input] can be a [String],
- * or [List<int>] of bytes and returns a [StyleSheet] AST.  The optional
- * [errors] list will contain each error/warning as a [Message].
- */
+/// Parse the [input] CSS stylesheet into a tree. The [input] can be a [String],
+/// or [List<int>] of bytes and returns a [StyleSheet] AST.  The optional
+/// [errors] list will contain each error/warning as a [Message].
 StyleSheet parse(input, {List<Message> errors, PreprocessorOptions options}) {
   var source = _inputAsString(input);
 
@@ -103,11 +101,9 @@
   return new _Parser(file, source).parse();
 }
 
-/**
- * Parse the [input] CSS selector into a tree. The [input] can be a [String],
- * or [List<int>] of bytes and returns a [StyleSheet] AST.  The optional
- * [errors] list will contain each error/warning as a [Message].
- */
+/// Parse the [input] CSS selector into a tree. The [input] can be a [String],
+/// or [List<int>] of bytes and returns a [StyleSheet] AST.  The optional
+/// [errors] list will contain each error/warning as a [Message].
 // TODO(jmesserly): should rename "parseSelector" and return Selector
 StyleSheet selector(input, {List<Message> errors}) {
   var source = _inputAsString(input);
@@ -126,8 +122,9 @@
 
   var file = new SourceFile.fromString(source);
   return (new _Parser(file, source)
-        // TODO(jmesserly): this fix should be applied to the parser. It's tricky
-        // because by the time the flag is set one token has already been fetched.
+        // TODO(jmesserly): this fix should be applied to the parser. It's
+        // tricky because by the time the flag is set one token has already
+        // been fetched.
         ..tokenizer.inSelector = true)
       .processSelectorGroup();
 }
@@ -165,7 +162,7 @@
 
 // TODO(terry): Consider removing this class when all usages can be eliminated
 //               or replaced with compile API.
-/** Public parsing interface for csslib. */
+/// Public parsing interface for csslib.
 class Parser {
   final _Parser _parser;
 
@@ -185,14 +182,12 @@
   'first-line',
 ]);
 
-/** A simple recursive descent parser for CSS. */
+/// A simple recursive descent parser for CSS.
 class _Parser {
   final Tokenizer tokenizer;
 
-  /**
-   * File containing the source being parsed, used to report errors with
-   * source-span locations.
-   */
+  /// File containing the source being parsed, used to report errors with
+  /// source-span locations.
   final SourceFile file;
 
   Token _previousToken;
@@ -204,7 +199,7 @@
     _peekToken = tokenizer.next();
   }
 
-  /** Main entry point for parsing an entire CSS file. */
+  /// Main entry point for parsing an entire CSS file.
   StyleSheet parse() {
     List<TreeNode> productions = [];
 
@@ -224,7 +219,7 @@
     return new StyleSheet(productions, _makeSpan(start));
   }
 
-  /** Main entry point for parsing a simple selector sequence. */
+  /// Main entry point for parsing a simple selector sequence.
   StyleSheet parseSelector() {
     List<TreeNode> productions = [];
 
@@ -241,7 +236,7 @@
     return new StyleSheet.selector(productions, _makeSpan(start));
   }
 
-  /** Generate an error if [file] has not been completely consumed. */
+  /// Generate an error if [file] has not been completely consumed.
   void checkEndOfFile() {
     if (!(_peekKind(TokenKind.END_OF_FILE) ||
         _peekKind(TokenKind.INCOMPLETE_COMMENT))) {
@@ -249,7 +244,7 @@
     }
   }
 
-  /** Guard to break out of parser when an unexpected end of file is found. */
+  /// Guard to break out of parser when an unexpected end of file is found.
   // TODO(jimhug): Failure to call this method can lead to inifinite parser
   //   loops.  Consider embracing exceptions for more errors to reduce
   //   the danger here.
@@ -279,16 +274,16 @@
     return _peekToken.kind == kind;
   }
 
-  /* Is the next token a legal identifier?  This includes pseudo-keywords. */
+  // Is the next token a legal identifier?  This includes pseudo-keywords.
   bool _peekIdentifier() {
     return TokenKind.isIdentifier(_peekToken.kind);
   }
 
-  /** Marks the parser/tokenizer look ahead to support Less nested selectors. */
+  /// Marks the parser/tokenizer look ahead to support Less nested selectors.
   ParserState get _mark =>
       new ParserState(_peekToken, _previousToken, tokenizer);
 
-  /** Restores the parser/tokenizer state to state remembered by _mark. */
+  /// Restores the parser/tokenizer state to state remembered by _mark.
   void _restore(ParserState markedData) {
     tokenizer.restore(markedData);
     _peekToken = markedData.peekToken;
@@ -350,22 +345,20 @@
   // Top level productions
   ///////////////////////////////////////////////////////////////////
 
-  /**
-   * The media_query_list production below replaces the media_list production
-   * from CSS2 the new grammar is:
-   *
-   *   media_query_list
-   *    : S* [media_query [ ',' S* media_query ]* ]?
-   *   media_query
-   *    : [ONLY | NOT]? S* media_type S* [ AND S* expression ]*
-   *    | expression [ AND S* expression ]*
-   *   media_type
-   *    : IDENT
-   *   expression
-   *    : '(' S* media_feature S* [ ':' S* expr ]? ')' S*
-   *   media_feature
-   *    : IDENT
-   */
+  /// The media_query_list production below replaces the media_list production
+  /// from CSS2 the new grammar is:
+  ///
+  ///     media_query_list
+  ///      : S* [media_query [ ',' S* media_query ]* ]?
+  ///     media_query
+  ///      : [ONLY | NOT]? S* media_type S* [ AND S* expression ]*
+  ///      | expression [ AND S* expression ]*
+  ///     media_type
+  ///      : IDENT
+  ///     expression
+  ///      : '(' S* media_feature S* [ ':' S* expr ]? ')' S*
+  ///     media_feature
+  ///      : IDENT
   List<MediaQuery> processMediaQueryList() {
     var mediaQueries = <MediaQuery>[];
 
@@ -459,28 +452,26 @@
     return null;
   }
 
-  /**
-   * Directive grammar:
-   *
-   *  import:             '@import' [string | URI] media_list?
-   *  media:              '@media' media_query_list '{' ruleset '}'
-   *  page:               '@page' [':' IDENT]? '{' declarations '}'
-   *  stylet:             '@stylet' IDENT '{' ruleset '}'
-   *  media_query_list:   IDENT [',' IDENT]
-   *  keyframes:          '@-webkit-keyframes ...' (see grammar below).
-   *  font_face:          '@font-face' '{' declarations '}'
-   *  namespace:          '@namespace name url("xmlns")
-   *  host:               '@host '{' ruleset '}'
-   *  mixin:              '@mixin name [(args,...)] '{' declarations/ruleset '}'
-   *  include:            '@include name [(@arg,@arg1)]
-   *                      '@include name [(@arg...)]
-   *  content:            '@content'
-   *  -moz-document:      '@-moz-document' [ <url> | url-prefix(<string>) |
-   *                          domain(<string>) | regexp(<string) ]# '{'
-   *                        declarations
-   *                      '}'
-   *  supports:           '@supports' supports_condition group_rule_body
-   */
+  /// Directive grammar:
+  ///
+  ///     import:             '@import' [string | URI] media_list?
+  ///     media:              '@media' media_query_list '{' ruleset '}'
+  ///     page:               '@page' [':' IDENT]? '{' declarations '}'
+  ///     stylet:             '@stylet' IDENT '{' ruleset '}'
+  ///     media_query_list:   IDENT [',' IDENT]
+  ///     keyframes:          '@-webkit-keyframes ...' (see grammar below).
+  ///     font_face:          '@font-face' '{' declarations '}'
+  ///     namespace:          '@namespace name url("xmlns")
+  ///     host:               '@host '{' ruleset '}'
+  ///     mixin:              '@mixin name [(args,...)] '{' declarations/ruleset '}'
+  ///     include:            '@include name [(@arg,@arg1)]
+  ///                         '@include name [(@arg...)]
+  ///     content:            '@content'
+  ///     -moz-document:      '@-moz-document' [ <url> | url-prefix(<string>) |
+  ///                             domain(<string>) | regexp(<string) ]# '{'
+  ///                           declarations
+  ///                         '}'
+  ///     supports:           '@supports' supports_condition group_rule_body
   processDirective() {
     var start = _peekToken.span;
 
@@ -553,22 +544,20 @@
         return new HostDirective(rules, _makeSpan(start));
 
       case TokenKind.DIRECTIVE_PAGE:
-        /*
-         * @page S* IDENT? pseudo_page?
-         *      S* '{' S*
-         *      [ declaration | margin ]?
-         *      [ ';' S* [ declaration | margin ]? ]* '}' S*
-         *
-         * pseudo_page :
-         *      ':' [ "left" | "right" | "first" ]
-         *
-         * margin :
-         *      margin_sym S* '{' declaration [ ';' S* declaration? ]* '}' S*
-         *
-         * margin_sym : @top-left-corner, @top-left, @bottom-left, etc.
-         *
-         * See http://www.w3.org/TR/css3-page/#CSS21
-         */
+        // @page S* IDENT? pseudo_page?
+        //      S* '{' S*
+        //      [ declaration | margin ]?
+        //      [ ';' S* [ declaration | margin ]? ]* '}' S*
+        //
+        // pseudo_page :
+        //      ':' [ "left" | "right" | "first" ]
+        //
+        // margin :
+        //      margin_sym S* '{' declaration [ ';' S* declaration? ]* '}' S*
+        //
+        // margin_sym : @top-left-corner, @top-left, @bottom-left, etc.
+        //
+        // See http://www.w3.org/TR/css3-page/#CSS21
         _next();
 
         // Page name
@@ -638,18 +627,17 @@
         }
         // TODO(terry): End of workaround.
 
-        /*  Key frames grammar:
-         *
-         *  @[browser]? keyframes [IDENT|STRING] '{' keyframes-blocks '}';
-         *
-         *  browser: [-webkit-, -moz-, -ms-, -o-]
-         *
-         *  keyframes-blocks:
-         *    [keyframe-selectors '{' declarations '}']* ;
-         *
-         *  keyframe-selectors:
-         *    ['from'|'to'|PERCENTAGE] [',' ['from'|'to'|PERCENTAGE] ]* ;
-         */
+        // Key frames grammar:
+        //
+        //     @[browser]? keyframes [IDENT|STRING] '{' keyframes-blocks '}';
+        //
+        //     browser: [-webkit-, -moz-, -ms-, -o-]
+        //
+        //     keyframes-blocks:
+        //       [keyframe-selectors '{' declarations '}']* ;
+        //
+        //     keyframe-selectors:
+        //       ['from'|'to'|PERCENTAGE] [',' ['from'|'to'|PERCENTAGE] ]* ;
         _next();
 
         var name;
@@ -683,12 +671,11 @@
         return new FontFaceDirective(processDeclarations(), _makeSpan(start));
 
       case TokenKind.DIRECTIVE_STYLET:
-        /* Stylet grammar:
-         *
-         *  @stylet IDENT '{'
-         *    ruleset
-         *  '}'
-         */
+        // Stylet grammar:
+        //
+        //     @stylet IDENT '{'
+        //       ruleset
+        //     '}'
         _next();
 
         var name;
@@ -714,12 +701,10 @@
         return new StyletDirective(name, productions, _makeSpan(start));
 
       case TokenKind.DIRECTIVE_NAMESPACE:
-        /* Namespace grammar:
-         *
-         * @namespace S* [namespace_prefix S*]? [STRING|URI] S* ';' S*
-         * namespace_prefix : IDENT
-         *
-         */
+        // Namespace grammar:
+        //
+        // @namespace S* [namespace_prefix S*]? [STRING|URI] S* ';' S*
+        // namespace_prefix : IDENT
         _next();
 
         var prefix;
@@ -771,16 +756,14 @@
     return null;
   }
 
-  /**
-   * Parse the mixin beginning token offset [start]. Returns a [MixinDefinition]
-   * node.
-   *
-   * Mixin grammar:
-   *
-   *  @mixin IDENT [(args,...)] '{'
-   *    [ruleset | property | directive]*
-   *  '}'
-   */
+  /// Parse the mixin beginning token offset [start]. Returns a
+  /// [MixinDefinition] node.
+  ///
+  /// Mixin grammar:
+  ///
+  ///     @mixin IDENT [(args,...)] '{'
+  ///       [ruleset | property | directive]*
+  ///     '}'
   MixinDefinition processMixin() {
     _next();
 
@@ -877,10 +860,8 @@
     return mixinDirective;
   }
 
-  /**
-   * Returns a VarDefinitionDirective or VarDefinition if a varaible otherwise
-   * return the token id of a directive or -1 if neither.
-   */
+  /// Returns a VarDefinitionDirective or VarDefinition if a varaible otherwise
+  /// return the token id of a directive or -1 if neither.
   processVariableOrDirective({bool mixinParameter: false}) {
     var start = _peekToken.span;
 
@@ -943,10 +924,9 @@
   }
 
   IncludeDirective processInclude(SourceSpan span, {bool eatSemiColon: true}) {
-    /* Stylet grammar:
-    *
-     *  @include IDENT [(args,...)];
-     */
+    // Stylet grammar:
+    //
+    //     @include IDENT [(args,...)];
     _next();
 
     var name;
@@ -1144,29 +1124,28 @@
     return nodes;
   }
 
-  /**
-   * Look ahead to see if what should be a declaration is really a selector.
-   * If it's a selector than it's a nested selector.  This support's Less'
-   * nested selector syntax (requires a look ahead). E.g.,
-   *
-   *    div {
-   *      width : 20px;
-   *      span {
-   *        color: red;
-   *      }
-   *    }
-   *
-   * Two tag name selectors div and span equivalent to:
-   *
-   *    div {
-   *      width: 20px;
-   *    }
-   *    div span {
-   *      color: red;
-   *    }
-   *
-   * Return [:null:] if no selector or [SelectorGroup] if a selector was parsed.
-   */
+  /// Look ahead to see if what should be a declaration is really a selector.
+  /// If it's a selector than it's a nested selector.  This support's Less'
+  /// nested selector syntax (requires a look ahead). E.g.,
+  ///
+  ///     div {
+  ///       width : 20px;
+  ///       span {
+  ///         color: red;
+  ///       }
+  ///     }
+  ///
+  /// Two tag name selectors div and span equivalent to:
+  ///
+  ///     div {
+  ///       width: 20px;
+  ///     }
+  ///     div span {
+  ///       color: red;
+  ///     }
+  ///
+  /// Return [:null:] if no selector or [SelectorGroup] if a selector was
+  /// parsed.
   SelectorGroup _nestedSelector() {
     Messages oldMessages = messages;
     _createMessages();
@@ -1352,9 +1331,7 @@
     return null;
   }
 
-  /**
-   * Return list of selectors
-   */
+  /// Return list of selectors
   Selector processSelector() {
     var simpleSequences = <SimpleSelectorSequence>[];
     var start = _peekToken.span;
@@ -1460,24 +1437,22 @@
     }
   }
 
-  /**
-   * Simple selector grammar:
-   *
-   *    simple_selector_sequence
-   *       : [ type_selector | universal ]
-   *         [ HASH | class | attrib | pseudo | negation ]*
-   *       | [ HASH | class | attrib | pseudo | negation ]+
-   *    type_selector
-   *       : [ namespace_prefix ]? element_name
-   *    namespace_prefix
-   *       : [ IDENT | '*' ]? '|'
-   *    element_name
-   *       : IDENT
-   *    universal
-   *       : [ namespace_prefix ]? '*'
-   *    class
-   *       : '.' IDENT
-   */
+  /// Simple selector grammar:
+  ///
+  ///     simple_selector_sequence
+  ///        : [ type_selector | universal ]
+  ///          [ HASH | class | attrib | pseudo | negation ]*
+  ///        | [ HASH | class | attrib | pseudo | negation ]+
+  ///     type_selector
+  ///        : [ namespace_prefix ]? element_name
+  ///     namespace_prefix
+  ///        : [ IDENT | '*' ]? '|'
+  ///     element_name
+  ///        : IDENT
+  ///     universal
+  ///        : [ namespace_prefix ]? '*'
+  ///     class
+  ///        : '.' IDENT
   simpleSelector() {
     // TODO(terry): Natalie makes a good point parsing of namespace and element
     //              are essentially the same (asterisk or identifier) other
@@ -1546,9 +1521,7 @@
     return false;
   }
 
-  /**
-   * type_selector | universal | HASH | class | attrib | pseudo
-   */
+  /// type_selector | universal | HASH | class | attrib | pseudo
   simpleSelectorTail() {
     // Check for HASH | class | attrib | pseudo | negation
     var start = _peekToken.span;
@@ -1672,16 +1645,14 @@
         : new PseudoClassSelector(pseudoName, _makeSpan(start));
   }
 
-  /**
-   *  In CSS3, the expressions are identifiers, strings, or of the form "an+b".
-   *
-   *    : [ [ PLUS | '-' | DIMENSION | NUMBER | STRING | IDENT ] S* ]+
-   *
-   *    num               [0-9]+|[0-9]*\.[0-9]+
-   *    PLUS              '+'
-   *    DIMENSION         {num}{ident}
-   *    NUMBER            {num}
-   */
+  /// In CSS3, the expressions are identifiers, strings, or of the form "an+b".
+  ///
+  ///     : [ [ PLUS | '-' | DIMENSION | NUMBER | STRING | IDENT ] S* ]+
+  ///
+  ///     num               [0-9]+|[0-9]*\.[0-9]+
+  ///     PLUS              '+'
+  ///     DIMENSION         {num}{ident}
+  ///     NUMBER            {num}
   processSelectorExpression() {
     var start = _peekToken.span;
 
@@ -1744,25 +1715,23 @@
     return new SelectorExpression(expressions, _makeSpan(start));
   }
 
-  //  Attribute grammar:
+  // Attribute grammar:
   //
-  //  attributes :
-  //    '[' S* IDENT S* [ ATTRIB_MATCHES S* [ IDENT | STRING ] S* ]? ']'
+  //     attributes :
+  //       '[' S* IDENT S* [ ATTRIB_MATCHES S* [ IDENT | STRING ] S* ]? ']'
   //
-  //  ATTRIB_MATCHES :
-  //    [ '=' | INCLUDES | DASHMATCH | PREFIXMATCH | SUFFIXMATCH | SUBSTRMATCH ]
+  //     ATTRIB_MATCHES :
+  //       [ '=' | INCLUDES | DASHMATCH | PREFIXMATCH | SUFFIXMATCH | SUBSTRMATCH ]
   //
-  //  INCLUDES:         '~='
+  //     INCLUDES:         '~='
   //
-  //  DASHMATCH:        '|='
+  //     DASHMATCH:        '|='
   //
-  //  PREFIXMATCH:      '^='
+  //     PREFIXMATCH:      '^='
   //
-  //  SUFFIXMATCH:      '$='
+  //     SUFFIXMATCH:      '$='
   //
-  //  SUBSTRMATCH:      '*='
-  //
-  //
+  //     SUBSTRMATCH:      '*='
   AttributeSelector processAttribute() {
     var start = _peekToken.span;
 
@@ -1817,7 +1786,6 @@
   //   property: expr prio? \9; - IE8 and below property, /9 before semi-colon
   //   *IDENT                   - IE7 or below
   //   _IDENT                   - IE6 property (automatically a valid ident)
-  //
   Declaration processDeclaration(List dartStyles) {
     Declaration decl;
 
@@ -1888,7 +1856,7 @@
     return decl;
   }
 
-  /** List of styles exposed to the Dart UI framework. */
+  /// List of styles exposed to the Dart UI framework.
   static const int _fontPartFont = 0;
   static const int _fontPartVariant = 1;
   static const int _fontPartWeight = 2;
@@ -1981,14 +1949,12 @@
   DartStyleExpression buildDartStyleNode(
       int styleType, Expressions exprs, List dartStyles) {
     switch (styleType) {
-      /*
-       * Properties in order:
-       *
-       *   font-style font-variant font-weight font-size/line-height font-family
-       *
-       * The font-size and font-family values are required. If other values are
-       * missing; a default, if it exist, will be used.
-       */
+      // Properties in order:
+      //
+      //     font-style font-variant font-weight font-size/line-height font-family
+      //
+      // The font-size and font-family values are required. If other values are
+      // missing; a default, if it exist, will be used.
       case _fontPartFont:
         var processor = new ExpressionsProcessor(exprs);
         return _mergeFontStyles(processor.processFont(), dartStyles);
@@ -2005,31 +1971,31 @@
         var processor = new ExpressionsProcessor(exprs);
         return _mergeFontStyles(processor.processFontSize(), dartStyles);
       case _fontPartStyle:
-        /* Possible style values:
-         *   normal [default]
-         *   italic
-         *   oblique
-         *   inherit
-         */
+        // Possible style values:
+        //   normal [default]
+        //   italic
+        //   oblique
+        //   inherit
+
         // TODO(terry): TBD
         break;
       case _fontPartVariant:
-        /* Possible variant values:
-         *   normal  [default]
-         *   small-caps
-         *   inherit
-         */
+        // Possible variant values:
+        //   normal  [default]
+        //   small-caps
+        //   inherit
+
         // TODO(terry): TBD
         break;
       case _fontPartWeight:
-        /* Possible weight values:
-         *   normal [default]
-         *   bold
-         *   bolder
-         *   lighter
-         *   100 - 900
-         *   inherit
-         */
+        // Possible weight values:
+        //   normal [default]
+        //   bold
+        //   bolder
+        //   lighter
+        //   100 - 900
+        //   inherit
+
         // TODO(terry): Only 'normal', 'bold', or values of 100-900 supoorted
         //              need to handle bolder, lighter, and inherit.  See
         //              https://github.com/dart-lang/csslib/issues/1
@@ -2159,16 +2125,14 @@
     return null;
   }
 
-  /**
-   * Margins are of the format:
-   *
-   *   top,right,bottom,left      (4 parameters)
-   *   top,right/left, bottom     (3 parameters)
-   *   top/bottom,right/left      (2 parameters)
-   *   top/right/bottom/left      (1 parameter)
-   *
-   * The values of the margins can be a unit or unitless or auto.
-   */
+  /// Margins are of the format:
+  ///
+  /// * top,right,bottom,left      (4 parameters)
+  /// * top,right/left, bottom     (3 parameters)
+  /// * top/bottom,right/left      (2 parameters)
+  /// * top/right/bottom/left      (1 parameter)
+  ///
+  /// The values of the margins can be a unit or unitless or auto.
   BoxEdge processFourNums(Expressions exprs) {
     num top;
     num right;
@@ -2221,7 +2185,6 @@
   //
   //  operator:     '/' | ','
   //  term:         (see processTerm)
-  //
   Expressions processExpr([bool ieFilter = false]) {
     var start = _peekToken.span;
     var expressions = new Expressions(_makeSpan(start));
@@ -2241,8 +2204,8 @@
           op = new OperatorComma(_makeSpan(opStart));
           break;
         case TokenKind.BACKSLASH:
-          // Backslash outside of string; detected IE8 or older signaled by \9 at
-          // end of an expression.
+          // Backslash outside of string; detected IE8 or older signaled by \9
+          // at end of an expression.
           var ie8Start = _peekToken.span;
 
           _next();
@@ -2286,26 +2249,26 @@
 
   static const int MAX_UNICODE = 0x10FFFF;
 
-  //  Term grammar:
+  // Term grammar:
   //
-  //  term:
-  //    unary_operator?
-  //    [ term_value ]
-  //    | STRING S* | IDENT S* | URI S* | UNICODERANGE S* | hexcolor
+  //     term:
+  //       unary_operator?
+  //       [ term_value ]
+  //       | STRING S* | IDENT S* | URI S* | UNICODERANGE S* | hexcolor
   //
-  //  term_value:
-  //    NUMBER S* | PERCENTAGE S* | LENGTH S* | EMS S* | EXS S* | ANGLE S* |
-  //    TIME S* | FREQ S* | function
+  //     term_value:
+  //       NUMBER S* | PERCENTAGE S* | LENGTH S* | EMS S* | EXS S* | ANGLE S* |
+  //       TIME S* | FREQ S* | function
   //
-  //  NUMBER:       {num}
-  //  PERCENTAGE:   {num}%
-  //  LENGTH:       {num}['px' | 'cm' | 'mm' | 'in' | 'pt' | 'pc']
-  //  EMS:          {num}'em'
-  //  EXS:          {num}'ex'
-  //  ANGLE:        {num}['deg' | 'rad' | 'grad']
-  //  TIME:         {num}['ms' | 's']
-  //  FREQ:         {num}['hz' | 'khz']
-  //  function:     IDENT '(' expr ')'
+  //     NUMBER:       {num}
+  //     PERCENTAGE:   {num}%
+  //     LENGTH:       {num}['px' | 'cm' | 'mm' | 'in' | 'pt' | 'pc']
+  //     EMS:          {num}'em'
+  //     EXS:          {num}'ex'
+  //     ANGLE:        {num}['deg' | 'rad' | 'grad']
+  //     TIME:         {num}['ms' | 's']
+  //     FREQ:         {num}['hz' | 'khz']
+  //     function:     IDENT '(' expr ')'
   //
   processTerm([bool ieFilter = false]) {
     var start = _peekToken.span;
@@ -2398,8 +2361,8 @@
             // IE filter:progid:
             return processIEFilter(start);
           } else {
-            // Handle filter:<name> where name is any filter e.g., alpha, chroma,
-            // Wave, blur, etc.
+            // Handle filter:<name> where name is any filter e.g., alpha,
+            // chroma, Wave, blur, etc.
             return processIEFilter(start);
           }
         }
@@ -2479,7 +2442,7 @@
     return t != null ? processDimension(t, value, _makeSpan(start)) : null;
   }
 
-  /** Process all dimension units. */
+  /// Process all dimension units.
   LiteralTerm processDimension(Token t, var value, SourceSpan span) {
     LiteralTerm term;
     var unitType = this._peek();
@@ -2613,14 +2576,12 @@
 
   // TODO(terry): Should probably understand IE's non-standard filter syntax to
   //              fully support calc, var(), etc.
-  /**
-   * IE's filter property breaks CSS value parsing.  IE's format can be:
-   *
-   *    filter: progid:DXImageTransform.MS.gradient(Type=0, Color='#9d8b83');
-   *
-   * We'll just parse everything after the 'progid:' look for the left paren
-   * then parse to the right paren ignoring everything in between.
-   */
+  /// IE's filter property breaks CSS value parsing.  IE's format can be:
+  ///
+  ///    filter: progid:DXImageTransform.MS.gradient(Type=0, Color='#9d8b83');
+  ///
+  /// We'll just parse everything after the 'progid:' look for the left paren
+  /// then parse to the right paren ignoring everything in between.
   processIEFilter(FileSpan startAfterProgidColon) {
     // Support non-functional filters (i.e. filter: FlipH)
     var kind = _peek();
@@ -2651,16 +2612,16 @@
     }
   }
 
-  //  TODO(terry): Hack to gobble up the calc expression as a string looking
-  //               for the matching RPAREN the expression is not parsed into the
-  //               AST.
+  // TODO(terry): Hack to gobble up the calc expression as a string looking
+  //              for the matching RPAREN the expression is not parsed into the
+  //              AST.
   //
-  //  grammar should be:
+  // grammar should be:
   //
-  //    <calc()> = calc( <calc-sum> )
-  //    <calc-sum> = <calc-product> [ [ '+' | '-' ] <calc-product> ]*
-  //    <calc-product> = <calc-value> [ '*' <calc-value> | '/' <number> ]*
-  //    <calc-value> = <number> | <dimension> | <percentage> | ( <calc-sum> )
+  //     <calc()> = calc( <calc-sum> )
+  //     <calc-sum> = <calc-product> [ [ '+' | '-' ] <calc-product> ]*
+  //     <calc-product> = <calc-value> [ '*' <calc-value> | '/' <number> ]*
+  //     <calc-value> = <number> | <dimension> | <percentage> | ( <calc-sum> )
   //
   String processCalcExpression() {
     var inString = tokenizer._inString;
@@ -2718,7 +2679,8 @@
 
     switch (name) {
       case 'url':
-        // URI term sucks up everything inside of quotes(' or ") or between parens
+        // URI term sucks up everything inside of quotes(' or ") or between
+        // parens.
         var urlParam = processQuotedString(true);
 
         // TODO(terry): Better error message and checking for mismatched quotes.
@@ -2732,9 +2694,10 @@
 
         return new UriTerm(urlParam, _makeSpan(start));
       case 'var':
-        // TODO(terry): Consider handling var in IE specific filter/progid.  This
-        //              will require parsing entire IE specific syntax e.g.,
-        //              param = value or progid:com_id, etc. for example:
+        // TODO(terry): Consider handling var in IE specific filter/progid.
+        //              This will require parsing entire IE specific syntax
+        //              e.g. `param = value` or `progid:com_id`, etc.
+        //              for example:
         //
         //    var-blur: Blur(Add = 0, Direction = 225, Strength = 10);
         //    var-gradient: progid:DXImageTransform.Microsoft.gradient"
@@ -2831,21 +2794,20 @@
 
   // TODO(terry): Only handles ##px unit.
   FontExpression processFontSize() {
-    /* font-size[/line-height]
-     *
-     * Possible size values:
-     *   xx-small
-     *   small
-     *   medium [default]
-     *   large
-     *   x-large
-     *   xx-large
-     *   smaller
-     *   larger
-     *   ##length in px, pt, etc.
-     *   ##%, percent of parent elem's font-size
-     *   inherit
-     */
+    // font-size[/line-height]
+    //
+    // Possible size values:
+    // * xx-small
+    // * small
+    // * medium [default]
+    // * large
+    // * x-large
+    // * xx-large
+    // * smaller
+    // * larger
+    // * ##length in px, pt, etc.
+    // * ##%, percent of parent elem's font-size
+    // * inherit
     LengthTerm size;
     LineHeight lineHt;
     var nextIsLineHeight = false;
@@ -2878,10 +2840,9 @@
   FontExpression processFontFamily() {
     var family = <String>[];
 
-    /* Possible family values:
-     * font-family: arial, Times new roman ,Lucida Sans Unicode,Courier;
-     * font-family: "Times New Roman", arial, Lucida Sans Unicode, Courier;
-     */
+    // Possible family values:
+    // * font-family: arial, Times new roman ,Lucida Sans Unicode,Courier;
+    // * font-family: "Times New Roman", arial, Lucida Sans Unicode, Courier;
     var moreFamilies = false;
 
     for (; _index < _exprs.expressions.length; _index++) {
@@ -2929,10 +2890,8 @@
   }
 }
 
-/**
- * Escapes [text] for use in a CSS string.
- * [single] specifies single quote `'` vs double quote `"`.
- */
+/// Escapes [text] for use in a CSS string.
+/// [single] specifies single quote `'` vs double quote `"`.
 String _escapeString(String text, {bool single: false}) {
   StringBuffer result = null;
 
diff --git a/lib/src/analyzer.dart b/lib/src/analyzer.dart
index 5a2b59e..1b19551 100644
--- a/lib/src/analyzer.dart
+++ b/lib/src/analyzer.dart
@@ -18,10 +18,8 @@
 //                  div { color: red; }
 // <http://www.w3.org/TR/css3-syntax/#at-rules>
 
-/**
- * Analysis phase will validate/fixup any new CSS feature or any SASS style
- * feature.
- */
+/// Analysis phase will validate/fixup any new CSS feature or any Sass style
+/// feature.
 class Analyzer {
   final List<StyleSheet> _styleSheets;
   final Messages _messages;
@@ -57,139 +55,137 @@
   }
 }
 
-/**
- * Traverse all rulesets looking for nested ones.  If a ruleset is in a
- * declaration group (implies nested selector) then generate new ruleset(s) at
- * level 0 of CSS using selector inheritance syntax (flattens the nesting).
- *
- * How the AST works for a rule [RuleSet] and nested rules.  First of all a
- * CSS rule [RuleSet] consist of a selector and a declaration e.g.,
- *
- *    selector {
- *      declaration
- *    }
- *
- * AST structure of a [RuleSet] is:
- *
- *    RuleSet
- *       SelectorGroup
- *         List<Selector>
- *            List<SimpleSelectorSequence>
- *              Combinator      // +, >, ~, DESCENDENT, or NONE
- *              SimpleSelector  // class, id, element, namespace, attribute
- *        DeclarationGroup
- *          List                // Declaration or RuleSet
- *
- * For the simple rule:
- *
- *    div + span { color: red; }
- *
- * the AST [RuleSet] is:
- *
- *    RuleSet
- *       SelectorGroup
- *         List<Selector>
- *          [0]
- *            List<SimpleSelectorSequence>
- *              [0] Combinator = COMBINATOR_NONE
- *                  ElementSelector (name = div)
- *              [1] Combinator = COMBINATOR_PLUS
- *                  ElementSelector (name = span)
- *        DeclarationGroup
- *          List                // Declarations or RuleSets
- *            [0]
- *              Declaration (property = color, expression = red)
- *
- * Usually a SelectorGroup contains 1 Selector.  Consider the selectors:
- *
- *    div { color: red; }
- *    a { color: red; }
- *
- * are equivalent to
- *
- *    div, a { color : red; }
- *
- * In the above the RuleSet would have a SelectorGroup with 2 selectors e.g.,
- *
- *    RuleSet
- *       SelectorGroup
- *         List<Selector>
- *          [0]
- *            List<SimpleSelectorSequence>
- *              [0] Combinator = COMBINATOR_NONE
- *                  ElementSelector (name = div)
- *          [1]
- *            List<SimpleSelectorSequence>
- *              [0] Combinator = COMBINATOR_NONE
- *                  ElementSelector (name = a)
- *        DeclarationGroup
- *          List                // Declarations or RuleSets
- *            [0]
- *              Declaration (property = color, expression = red)
- *
- * For a nested rule e.g.,
- *
- *    div {
- *      color : blue;
- *      a { color : red; }
- *    }
- *
- * Would map to the follow CSS rules:
- *
- *    div { color: blue; }
- *    div a { color: red; }
- *
- * The AST for the former nested rule is:
- *
- *    RuleSet
- *       SelectorGroup
- *         List<Selector>
- *          [0]
- *            List<SimpleSelectorSequence>
- *              [0] Combinator = COMBINATOR_NONE
- *                  ElementSelector (name = div)
- *        DeclarationGroup
- *          List                // Declarations or RuleSets
- *            [0]
- *              Declaration (property = color, expression = blue)
- *            [1]
- *              RuleSet
- *                SelectorGroup
- *                  List<Selector>
- *                    [0]
- *                      List<SimpleSelectorSequence>
- *                        [0] Combinator = COMBINATOR_NONE
- *                            ElementSelector (name = a)
- *                DeclarationGroup
- *                  List                // Declarations or RuleSets
- *                    [0]
- *                      Declaration (property = color, expression = red)
- *
- * Nested rules is a terse mechanism to describe CSS inheritance.  The analyzer
- * will flatten and expand the nested rules to it's flatten strucure.  Using the
- * all parent [RuleSets] (selector expressions) and applying each nested
- * [RuleSet] to the list of [Selectors] in a [SelectorGroup].
- *
- * Then result is a style sheet where all nested rules have been flatten and
- * expanded.
- */
+/// Traverse all rulesets looking for nested ones.  If a ruleset is in a
+/// declaration group (implies nested selector) then generate new ruleset(s) at
+/// level 0 of CSS using selector inheritance syntax (flattens the nesting).
+///
+/// How the AST works for a rule [RuleSet] and nested rules.  First of all a
+/// CSS rule [RuleSet] consist of a selector and a declaration e.g.,
+///
+///     selector {
+///       declaration
+///     }
+///
+/// AST structure of a [RuleSet] is:
+///
+///     RuleSet
+///        SelectorGroup
+///          List<Selector>
+///             List<SimpleSelectorSequence>
+///               Combinator      // +, >, ~, DESCENDENT, or NONE
+///               SimpleSelector  // class, id, element, namespace, attribute
+///         DeclarationGroup
+///           List                // Declaration or RuleSet
+///
+/// For the simple rule:
+///
+///     div + span { color: red; }
+///
+/// the AST [RuleSet] is:
+///
+///     RuleSet
+///        SelectorGroup
+///          List<Selector>
+///           [0]
+///             List<SimpleSelectorSequence>
+///               [0] Combinator = COMBINATOR_NONE
+///                   ElementSelector (name = div)
+///               [1] Combinator = COMBINATOR_PLUS
+///                   ElementSelector (name = span)
+///         DeclarationGroup
+///           List                // Declarations or RuleSets
+///             [0]
+///               Declaration (property = color, expression = red)
+///
+/// Usually a SelectorGroup contains 1 Selector.  Consider the selectors:
+///
+///     div { color: red; }
+///     a { color: red; }
+///
+/// are equivalent to
+///
+///     div, a { color : red; }
+///
+/// In the above the RuleSet would have a SelectorGroup with 2 selectors e.g.,
+///
+///     RuleSet
+///        SelectorGroup
+///          List<Selector>
+///           [0]
+///             List<SimpleSelectorSequence>
+///               [0] Combinator = COMBINATOR_NONE
+///                   ElementSelector (name = div)
+///           [1]
+///             List<SimpleSelectorSequence>
+///               [0] Combinator = COMBINATOR_NONE
+///                   ElementSelector (name = a)
+///         DeclarationGroup
+///           List                // Declarations or RuleSets
+///             [0]
+///               Declaration (property = color, expression = red)
+///
+/// For a nested rule e.g.,
+///
+///     div {
+///       color : blue;
+///       a { color : red; }
+///     }
+///
+/// Would map to the follow CSS rules:
+///
+///     div { color: blue; }
+///     div a { color: red; }
+///
+/// The AST for the former nested rule is:
+///
+///     RuleSet
+///        SelectorGroup
+///          List<Selector>
+///           [0]
+///             List<SimpleSelectorSequence>
+///               [0] Combinator = COMBINATOR_NONE
+///                   ElementSelector (name = div)
+///         DeclarationGroup
+///           List                // Declarations or RuleSets
+///             [0]
+///               Declaration (property = color, expression = blue)
+///             [1]
+///               RuleSet
+///                 SelectorGroup
+///                   List<Selector>
+///                     [0]
+///                       List<SimpleSelectorSequence>
+///                         [0] Combinator = COMBINATOR_NONE
+///                             ElementSelector (name = a)
+///                 DeclarationGroup
+///                   List                // Declarations or RuleSets
+///                     [0]
+///                       Declaration (property = color, expression = red)
+///
+/// Nested rules is a terse mechanism to describe CSS inheritance.  The analyzer
+/// will flatten and expand the nested rules to it's flatten strucure.  Using
+/// the all parent [RuleSets] (selector expressions) and applying each nested
+/// [RuleSet] to the list of [Selectors] in a [SelectorGroup].
+///
+/// Then result is a style sheet where all nested rules have been flatten and
+/// expanded.
 class ExpandNestedSelectors extends Visitor {
-  /** Parent [RuleSet] if a nested rule otherwise [:null:]. */
+  /// Parent [RuleSet] if a nested rule otherwise [:null:].
   RuleSet _parentRuleSet;
 
-  /** Top-most rule if nested rules. */
+  /// Top-most rule if nested rules.
   SelectorGroup _topLevelSelectorGroup;
 
-  /** SelectorGroup at each nesting level. */
+  /// SelectorGroup at each nesting level.
   SelectorGroup _nestedSelectorGroup;
 
-  /** Declaration (sans the nested selectors). */
+  /// Declaration (sans the nested selectors).
   DeclarationGroup _flatDeclarationGroup;
 
-  /** Each nested selector get's a flatten RuleSet. */
+  /// Each nested selector get's a flatten RuleSet.
   List<RuleSet> _expandedRuleSets = [];
 
-  /** Maping of a nested rule set to the fully expanded list of RuleSet(s). */
+  /// Maping of a nested rule set to the fully expanded list of RuleSet(s).
   final Map<RuleSet, List<RuleSet>> _expansions = new Map();
 
   void visitRuleSet(RuleSet node) {
@@ -232,11 +228,9 @@
     }
   }
 
-  /**
-   * Build up the list of all inherited sequences from the parent selector
-   * [node] is the current nested selector and it's parent is the last entry in
-   * the [_nestedSelectorGroup].
-   */
+  /// Build up the list of all inherited sequences from the parent selector
+  /// [node] is the current nested selector and it's parent is the last entry in
+  /// the [_nestedSelectorGroup].
   SelectorGroup _mergeToFlatten(RuleSet node) {
     // Create a new SelectorGroup for this nesting level.
     var nestedSelectors = _nestedSelectorGroup.selectors;
@@ -255,10 +249,8 @@
     return new SelectorGroup(newSelectors, node.span);
   }
 
-  /**
-   * Merge the nested selector sequences [current] to the [parent] sequences or
-   * substitue any & with the parent selector.
-   */
+  /// Merge the nested selector sequences [current] to the [parent] sequences or
+  /// substitue any & with the parent selector.
   List<SimpleSelectorSequence> _mergeNestedSelector(
       List<SimpleSelectorSequence> parent,
       List<SimpleSelectorSequence> current) {
@@ -291,12 +283,10 @@
     return newSequence;
   }
 
-  /**
-   * Return selector sequences with first sequence combinator being a
-   * descendant.  Used for nested selectors when the parent selector needs to
-   * be prefixed to a nested selector or to substitute the this (&) with the
-   * parent selector.
-   */
+  /// Return selector sequences with first sequence combinator being a
+  /// descendant.  Used for nested selectors when the parent selector needs to
+  /// be prefixed to a nested selector or to substitute the this (&) with the
+  /// parent selector.
   List<SimpleSelectorSequence> _convertToDescendentSequence(
       List<SimpleSelectorSequence> sequences) {
     if (sequences.isEmpty) return sequences;
@@ -376,9 +366,8 @@
     super.visitMarginGroup(node);
   }
 
-  /**
-   * Replace the rule set that contains nested rules with the flatten rule sets.
-   */
+  /// Replace the rule set that contains nested rules with the flatten rule
+  /// sets.
   void flatten(StyleSheet styleSheet) {
     // TODO(terry): Iterate over topLevels instead of _expansions it's already
     //              a map (this maybe quadratic).
@@ -401,10 +390,9 @@
   List<RuleSet> _newRules;
   bool _foundAndReplaced = false;
 
-  /**
-   * Look for the [ruleSet] inside of an @media directive; if found then replace
-   * with the [newRules].  If [ruleSet] is found and replaced return true.
-   */
+  /// Look for the [ruleSet] inside of an @media directive; if found then
+  /// replace with the [newRules].  If [ruleSet] is found and replaced return
+  /// true.
   static bool replace(
       StyleSheet styleSheet, RuleSet ruleSet, List<RuleSet> newRules) {
     var visitor = new _MediaRulesReplacer(ruleSet, newRules);
@@ -423,14 +411,12 @@
   }
 }
 
-/**
- * Expand all @include at the top-level the ruleset(s) associated with the
- * mixin.
- */
+/// Expand all @include at the top-level the ruleset(s) associated with the
+/// mixin.
 class TopLevelIncludes extends Visitor {
   StyleSheet _styleSheet;
   final Messages _messages;
-  /** Map of variable name key to it's definition. */
+  /// Map of variable name key to it's definition.
   final Map<String, MixinDefinition> map = new Map<String, MixinDefinition>();
   MixinDefinition currDef;
 
@@ -504,17 +490,16 @@
   }
 }
 
-/** @include as a top-level with ruleset(s). */
+/// @include as a top-level with ruleset(s).
 class _TopLevelIncludeReplacer extends Visitor {
   final Messages _messages;
   final IncludeDirective _include;
   final List<TreeNode> _newRules;
   bool _foundAndReplaced = false;
 
-  /**
-   * Look for the [ruleSet] inside of an @media directive; if found then replace
-   * with the [newRules].  If [ruleSet] is found and replaced return true.
-   */
+  /// Look for the [ruleSet] inside of an @media directive; if found then
+  /// replace with the [newRules].  If [ruleSet] is found and replaced return
+  /// true.
   static bool replace(Messages messages, StyleSheet styleSheet,
       IncludeDirective include, List<TreeNode> newRules) {
     var visitor = new _TopLevelIncludeReplacer(messages, include, newRules);
@@ -546,11 +531,9 @@
   }
 }
 
-/**
- * Utility function to match an include to a list of either Declarations or
- * RuleSets, depending on type of mixin (ruleset or declaration).  The include
- * can be an include in a declaration or an include directive (top-level).
- */
+/// Utility function to match an include to a list of either Declarations or
+/// RuleSets, depending on type of mixin (ruleset or declaration).  The include
+/// can be an include in a declaration or an include directive (top-level).
 int _findInclude(List list, var node) {
   IncludeDirective matchNode =
       (node is IncludeMixinAtDeclaration) ? node.include : node;
@@ -564,10 +547,8 @@
   return -1;
 }
 
-/**
- * Stamp out a mixin with the defined args substituted with the user's
- * parameters.
- */
+/// Stamp out a mixin with the defined args substituted with the user's
+/// parameters.
 class CallMixin extends Visitor {
   final MixinDefinition mixinDef;
   List _definedArgs;
@@ -576,7 +557,7 @@
 
   final varUsages = new Map<String, Map<Expressions, Set<int>>>();
 
-  /** Only var defs with more than one expression (comma separated). */
+  /// Only var defs with more than one expression (comma separated).
   final Map<String, VarDefinition> varDefs;
 
   CallMixin(this.mixinDef, [this.varDefs]) {
@@ -587,10 +568,8 @@
     }
   }
 
-  /**
-   * Given a mixin's defined arguments return a cloned mixin defintion that has
-   * replaced all defined arguments with user's supplied VarUsages.
-   */
+  /// Given a mixin's defined arguments return a cloned mixin defintion that has
+  /// replaced all defined arguments with user's supplied VarUsages.
   MixinDefinition transform(List<List<Expression>> callArgs) {
     // TODO(terry): Handle default arguments and varArgs.
     // Transform mixin with callArgs.
@@ -626,7 +605,7 @@
     return mixinDef.clone();
   }
 
-  /** Rip apart var def with multiple parameters. */
+  /// Rip apart var def with multiple parameters.
   List<List<Expression>> _varDefsAsCallArgs(var callArg) {
     var defArgs = <List<Expression>>[];
     if (callArg is List && callArg[0] is VarUsage) {
@@ -691,18 +670,18 @@
   }
 }
 
-/** Expand all @include inside of a declaration associated with a mixin. */
+/// Expand all @include inside of a declaration associated with a mixin.
 class DeclarationIncludes extends Visitor {
   StyleSheet _styleSheet;
   final Messages _messages;
-  /** Map of variable name key to it's definition. */
+  /// Map of variable name key to it's definition.
   final Map<String, MixinDefinition> map = new Map<String, MixinDefinition>();
-  /** Cache of mixin called with parameters. */
+  /// Cache of mixin called with parameters.
   final Map<String, CallMixin> callMap = new Map<String, CallMixin>();
   MixinDefinition currDef;
   DeclarationGroup currDeclGroup;
 
-  /** Var definitions with more than 1 expression. */
+  /// Var definitions with more than 1 expression.
   final Map<String, VarDefinition> varDefs = new Map<String, VarDefinition>();
 
   static void expand(Messages messages, List<StyleSheet> styleSheets) {
@@ -837,16 +816,14 @@
   }
 }
 
-/** @include as a top-level with ruleset(s). */
+/// @include as a top-level with ruleset(s).
 class _IncludeReplacer extends Visitor {
   final _include;
   final List<TreeNode> _newDeclarations;
   bool _foundAndReplaced = false;
 
-  /**
-   * Look for the [ruleSet] inside of a @media directive; if found then replace
-   * with the [newRules].
-   */
+  /// Look for the [ruleSet] inside of a @media directive; if found then replace
+  /// with the [newRules].
   static void replace(
       StyleSheet ss, var include, List<TreeNode> newDeclarations) {
     var visitor = new _IncludeReplacer(include, newDeclarations);
@@ -867,9 +844,8 @@
   }
 }
 
-/**
- * Remove all @mixin and @include and any NoOp used as placeholder for @include.
- */
+/// Remove all @mixin and @include and any NoOp used as placeholder for
+/// @include.
 class MixinsAndIncludes extends Visitor {
   static void remove(StyleSheet styleSheet) {
     new MixinsAndIncludes()..visitStyleSheet(styleSheet);
@@ -899,7 +875,7 @@
   }
 }
 
-/** Find all @extend to create inheritance. */
+/// Find all @extend to create inheritance.
 class AllExtends extends Visitor {
   final Map<String, List<SelectorGroup>> inherits =
       new Map<String, List<SelectorGroup>>();
@@ -957,9 +933,7 @@
 // TODO(terry): Need to handle merging selector sequences
 // TODO(terry): Need to handle @extend-Only selectors.
 // TODO(terry): Need to handle !optional glag.
-/**
- * Changes any selector that matches @extend.
- */
+/// Changes any selector that matches @extend.
 class InheritExtends extends Visitor {
   final Messages _messages;
   final AllExtends _allExtends;
diff --git a/lib/src/css_printer.dart b/lib/src/css_printer.dart
index ada2b26..7fec014 100644
--- a/lib/src/css_printer.dart
+++ b/lib/src/css_printer.dart
@@ -4,29 +4,25 @@
 
 part of csslib.visitor;
 
-/**
- * Visitor that produces a formatted string representation of the CSS tree.
- */
+/// Visitor that produces a formatted string representation of the CSS tree.
 class CssPrinter extends Visitor {
   StringBuffer _buff = new StringBuffer();
   bool prettyPrint = true;
 
-  /**
-   * Walk the [tree] Stylesheet. [pretty] if true emits line breaks, extra
-   * spaces, friendly property values, etc., if false emits compacted output.
-   */
+  /// Walk the [tree] Stylesheet. [pretty] if true emits line breaks, extra
+  /// spaces, friendly property values, etc., if false emits compacted output.
   void visitTree(StyleSheet tree, {bool pretty: false}) {
     prettyPrint = pretty;
     _buff = new StringBuffer();
     visitStyleSheet(tree);
   }
 
-  /** Appends [str] to the output buffer. */
+  /// Appends [str] to the output buffer.
   void emit(String str) {
     _buff.write(str);
   }
 
-  /** Returns the output buffer. */
+  /// Returns the output buffer.
   String toString() => _buff.toString().trim();
 
   String get _newLine => prettyPrint ? '\n' : '';
@@ -155,11 +151,9 @@
     emit('$_newLine}');
   }
 
-  /**
-   *  @page : pseudoPage {
-   *    decls
-   *  }
-   */
+  ///  @page : pseudoPage {
+  ///    decls
+  ///  }
   void visitPageDirective(PageDirective node) {
     emit('$_newLine@page');
     if (node.hasIdent || node.hasPseudoPage) {
@@ -177,7 +171,7 @@
     emit('}');
   }
 
-  /** @charset "charset encoding" */
+  /// @charset "charset encoding"
   void visitCharsetDirective(CharsetDirective node) {
     emit('$_newLine@charset "${node.charEncoding}";');
   }
@@ -265,10 +259,8 @@
     emit('}');
   }
 
-  /**
-   * Added optional newLine for handling @include at top-level vs/ inside of
-   * a declaration group.
-   */
+  /// Added optional newLine for handling @include at top-level vs/ inside of
+  /// a declaration group.
   void visitIncludeDirective(IncludeDirective node, [bool topLevel = true]) {
     if (topLevel) emit(_newLine);
     emit('@include ${node.name}');
diff --git a/lib/src/messages.dart b/lib/src/messages.dart
index 420c243..3fe079b 100644
--- a/lib/src/messages.dart
+++ b/lib/src/messages.dart
@@ -12,7 +12,7 @@
 // TODO(terry): Remove the global messages, use some object that tracks
 //              compilation state.
 
-/** The global [Messages] for tracking info/warnings/messages. */
+/// The global [Messages] for tracking info/warnings/messages.
 Messages messages;
 
 // Color constants used for generating messages.
@@ -21,7 +21,7 @@
 final String MAGENTA_COLOR = '\u001b[35m';
 final String NO_COLOR = '\u001b[0m';
 
-/** Map between error levels and their display color. */
+/// Map between error levels and their display color.
 final Map<Level, String> _ERROR_COLORS = (() {
   var colorsMap = new Map<Level, String>();
   colorsMap[Level.SEVERE] = RED_COLOR;
@@ -30,7 +30,7 @@
   return colorsMap;
 })();
 
-/** Map between error levels and their friendly name. */
+/// Map between error levels and their friendly name.
 final Map<Level, String> _ERROR_LABEL = (() {
   var labels = new Map<Level, String>();
   labels[Level.SEVERE] = 'error';
@@ -39,7 +39,7 @@
   return labels;
 })();
 
-/** A single message from the compiler. */
+/// A single message from the compiler.
 class Message {
   final Level level;
   final String message;
@@ -71,12 +71,10 @@
 
 typedef void PrintHandler(Message obj);
 
-/**
- * This class tracks and prints information, warnings, and errors emitted by the
- * compiler.
- */
+/// This class tracks and prints information, warnings, and errors emitted by
+/// the compiler.
 class Messages {
-  /** Called on every error. Set to blank function to supress printing. */
+  /// Called on every error. Set to blank function to supress printing.
   final PrintHandler printHandler;
 
   final PreprocessorOptions options;
@@ -86,7 +84,7 @@
   Messages({PreprocessorOptions options, this.printHandler: print})
       : options = options != null ? options : new PreprocessorOptions();
 
-  /** Report a compile-time CSS error. */
+  /// Report a compile-time CSS error.
   void error(String message, SourceSpan span) {
     var msg = new Message(Level.SEVERE, message,
         span: span, useColors: options.useColors);
@@ -96,7 +94,7 @@
     printHandler(msg);
   }
 
-  /** Report a compile-time CSS warning. */
+  /// Report a compile-time CSS warning.
   void warning(String message, SourceSpan span) {
     if (options.warningsAsErrors) {
       error(message, span);
@@ -108,7 +106,7 @@
     }
   }
 
-  /** Report and informational message about what the compiler is doing. */
+  /// Report and informational message about what the compiler is doing.
   void info(String message, SourceSpan span) {
     var msg = new Message(Level.INFO, message,
         span: span, useColors: options.useColors);
@@ -118,7 +116,7 @@
     if (options.verbose) printHandler(msg);
   }
 
-  /** Merge [newMessages] to this message lsit. */
+  /// Merge [newMessages] to this message lsit.
   void mergeMessages(Messages newMessages) {
     messages.addAll(newMessages.messages);
     newMessages.messages
diff --git a/lib/src/options.dart b/lib/src/options.dart
index 56c358b..19130fe 100644
--- a/lib/src/options.dart
+++ b/lib/src/options.dart
@@ -5,37 +5,35 @@
 library csslib.src.options;
 
 class PreprocessorOptions {
-  /** Generate polyfill code (e.g., var, etc.) */
+  /// Generate polyfill code (e.g., var, etc.)
   final bool polyfill;
 
-  /** Report warnings as errors. */
+  /// Report warnings as errors.
   final bool warningsAsErrors;
 
-  /** Throw an exception on warnings (not used by command line tool). */
+  /// Throw an exception on warnings (not used by command line tool).
   final bool throwOnWarnings;
 
-  /** Throw an exception on errors (not used by command line tool). */
+  /// Throw an exception on errors (not used by command line tool).
   final bool throwOnErrors;
 
-  /** True to show informational messages. The `--verbose` flag. */
+  /// True to show informational messages. The `--verbose` flag.
   final bool verbose;
 
-  /** True to show warning messages for bad CSS.  The '--checked' flag. */
+  /// True to show warning messages for bad CSS.  The '--checked' flag.
   final bool checked;
 
   // TODO(terry): Add mixin support and nested rules.
-  /**
-   * Subset of Less commands enabled; disable with '--no-less'.
-   * Less syntax supported:
-   * - @name at root level statically defines variables resolved at compilation
-   * time.  Essentially a directive e.g., @var-name.
-   */
+  /// Subset of Less commands enabled; disable with '--no-less'.
+  /// Less syntax supported:
+  /// - @name at root level statically defines variables resolved at compilation
+  /// time.  Essentially a directive e.g., @var-name.
   final bool lessSupport;
 
-  /** Whether to use colors to print messages on the terminal. */
+  /// Whether to use colors to print messages on the terminal.
   final bool useColors;
 
-  /** File to process by the compiler. */
+  /// File to process by the compiler.
   final String inputFile;
 
   const PreprocessorOptions(
diff --git a/lib/src/polyfill.dart b/lib/src/polyfill.dart
index 9bdcbe2..fc6cc5f 100644
--- a/lib/src/polyfill.dart
+++ b/lib/src/polyfill.dart
@@ -4,10 +4,8 @@
 
 part of csslib.parser;
 
-/**
- * CSS polyfill emits CSS to be understood by older parsers that which do not
- * understand (var, calc, etc.).
- */
+/// CSS polyfill emits CSS to be understood by older parsers that which do not
+/// understand (var, calc, etc.).
 class PolyFill {
   final Messages _messages;
   Map<String, VarDefinition> _allVarDefinitions =
@@ -15,17 +13,13 @@
 
   Set<StyleSheet> allStyleSheets = new Set<StyleSheet>();
 
-  /**
-   * [_pseudoElements] list of known pseudo attributes found in HTML, any
-   * CSS pseudo-elements 'name::custom-element' is mapped to the manged name
-   * associated with the pseudo-element key.
-   */
+  /// [_pseudoElements] list of known pseudo attributes found in HTML, any
+  /// CSS pseudo-elements 'name::custom-element' is mapped to the manged name
+  /// associated with the pseudo-element key.
   PolyFill(this._messages);
 
-  /**
-   * Run the analyzer on every file that is a style sheet or any component that
-   * has a style tag.
-   */
+  /// Run the analyzer on every file that is a style sheet or any component that
+  /// has a style tag.
   void process(StyleSheet styleSheet, {List<StyleSheet> includes: null}) {
     if (includes != null) {
       processVarDefinitions(includes);
@@ -36,7 +30,7 @@
     new _RemoveVarDefinitions().visitTree(styleSheet);
   }
 
-  /** Process all includes looking for var definitions. */
+  /// Process all includes looking for var definitions.
   void processVarDefinitions(List<StyleSheet> includes) {
     for (var include in includes) {
       _allVarDefinitions = (new _VarDefinitionsIncludes(_allVarDefinitions)
@@ -62,7 +56,7 @@
   }
 }
 
-/** Build list of all var definitions in all includes. */
+/// Build list of all var definitions in all includes.
 class _VarDefinitionsIncludes extends Visitor {
   final Map<String, VarDefinition> varDefs;
 
@@ -83,10 +77,8 @@
   }
 }
 
-/**
- * Find var- definitions in a style sheet.
- * [found] list of known definitions.
- */
+/// Find var- definitions in a style sheet.
+/// [found] list of known definitions.
 class _VarDefAndUsage extends Visitor {
   final Messages _messages;
   final Map<String, VarDefinition> _knownVarDefs;
@@ -206,7 +198,7 @@
   }
 }
 
-/** Remove all var definitions. */
+/// Remove all var definitions.
 class _RemoveVarDefinitions extends Visitor {
   void visitTree(StyleSheet tree) {
     visitStyleSheet(tree);
@@ -223,7 +215,7 @@
   }
 }
 
-/** Find terminal definition (non VarUsage implies real CSS value). */
+/// Find terminal definition (non VarUsage implies real CSS value).
 VarDefinition _findTerminalVarDefinition(
     Map<String, VarDefinition> varDefs, VarDefinition varDef) {
   var expressions = varDef.expression as Expressions;
diff --git a/lib/src/property.dart b/lib/src/property.dart
index c6b9ccf..cf614fe 100644
--- a/lib/src/property.dart
+++ b/lib/src/property.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.
 
-/** Representations of CSS styles. */
+/// Representations of CSS styles.
 
 part of csslib.parser;
 
@@ -11,46 +11,34 @@
 //              the complexity can be removed.
 //              See https://github.com/dart-lang/csslib/issues/7
 
-/**
- * Base for all style properties (e.g., Color, Font, Border, Margin, etc.)
- */
+/// Base for all style properties (e.g., Color, Font, Border, Margin, etc.)
 abstract class _StyleProperty {
-  /**
-   * Returns the expression part of a CSS declaration.  Declaration is:
-   *
-   *     property:expression;
-   *
-   * E.g., if property is color then expression could be rgba(255,255,0) the
-   *       CSS declaration would be 'color:rgba(255,255,0);'.
-   *
-   * then _cssExpression would return 'rgba(255,255,0)'.  See
-   * <http://www.w3.org/TR/CSS21/grammar.html>
-   */
+  /// Returns the expression part of a CSS declaration.  Declaration is:
+  ///
+  ///     property:expression;
+  ///
+  /// E.g., if property is color then expression could be rgba(255,255,0) the
+  ///       CSS declaration would be 'color:rgba(255,255,0);'.
+  ///
+  /// then _cssExpression would return 'rgba(255,255,0)'.  See
+  /// <http://www.w3.org/TR/CSS21/grammar.html>
   String get cssExpression;
 }
 
-/**
- * Base interface for Color, HSL and RGB.
- */
+/// Base interface for Color, HSL and RGB.
 abstract class ColorBase {
-  /**
-   * Canonical form for color #rrggbb with alpha blending (0.0 == full
-   * transparency and 1.0 == fully opaque). If _argb length is 6 it's an
-   * rrggbb otherwise it's aarrggbb.
-   */
+  /// Canonical form for color #rrggbb with alpha blending (0.0 == full
+  /// transparency and 1.0 == fully opaque). If _argb length is 6 it's an
+  /// rrggbb otherwise it's aarrggbb.
   String toHexArgbString();
 
-  /**
-   * Return argb as a value (int).
-   */
+  /// Return argb as a value (int).
   int get argbValue;
 }
 
-/**
- * General purpse Color class.  Represent a color as an ARGB value that can be
- * converted to and from num, hex string, hsl, hsla, rgb, rgba and SVG pre-
- * defined color constant.
- */
+/// General purpse Color class.  Represent a color as an ARGB value that can be
+/// converted to and from num, hex string, hsl, hsla, rgb, rgba and SVG pre-
+/// defined color constant.
 class Color implements _StyleProperty, ColorBase {
   // If _argb length is 6 it's an rrggbb otherwise it's aarrggbb.
   final String _argb;
@@ -59,25 +47,21 @@
   //              converting from Color to an Rgba or Hsla for reading only.
   //              Usefulness of creating an Rgba or Hsla is limited.
 
-  /**
-   * Create a color with an integer representing the rgb value of red, green,
-   * and blue.  The value 0xffffff is the color white #ffffff (CSS style).
-   * The [rgb] value of 0xffd700 would map to #ffd700 or the constant
-   * Color.gold, where ff is red intensity, d7 is green intensity, and 00 is
-   * blue intensity.
-   */
+  /// Create a color with an integer representing the rgb value of red, green,
+  /// and blue.  The value 0xffffff is the color white #ffffff (CSS style).
+  /// The [rgb] value of 0xffd700 would map to #ffd700 or the constant
+  /// Color.gold, where ff is red intensity, d7 is green intensity, and 00 is
+  /// blue intensity.
   Color(int rgb, [num alpha]) : this._argb = Color._rgbToArgbString(rgb, alpha);
 
-  /**
-   * RGB takes three values. The [red], [green], and [blue] parameters are
-   * the intensity of those components where '0' is the least and '256' is the
-   * greatest.
-   *
-   * If [alpha] is provided, it is the level of translucency which ranges from
-   * '0' (completely transparent) to '1.0' (completely opaque).  It will
-   * internally be mapped to an int between '0' and '255' like the other color
-   * components.
-   */
+  /// RGB takes three values. The [red], [green], and [blue] parameters are
+  /// the intensity of those components where '0' is the least and '256' is the
+  /// greatest.
+  ///
+  /// If [alpha] is provided, it is the level of translucency which ranges from
+  /// '0' (completely transparent) to '1.0' (completely opaque).  It will
+  /// internally be mapped to an int between '0' and '255' like the other color
+  /// components.
   Color.createRgba(int red, int green, int blue, [num alpha])
       : this._argb = Color.convertToHexString(
             Color._clamp(red, 0, 255),
@@ -85,26 +69,22 @@
             Color._clamp(blue, 0, 255),
             alpha != null ? Color._clamp(alpha, 0, 1) : alpha);
 
-  /**
-   * Creates a new color from a CSS color string. For more information, see
-   * <https://developer.mozilla.org/en/CSS/color>.
-   */
+  /// Creates a new color from a CSS color string. For more information, see
+  /// <https://developer.mozilla.org/en/CSS/color>.
   Color.css(String color) : this._argb = Color._convertCssToArgb(color);
 
   // TODO(jmesserly): I found the use of percents a bit suprising.
-  /**
-   * HSL takes three values.  The [hueDegree] degree on the color wheel; '0' is
-   * the least and '100' is the greatest.  The value '0' or '360' is red, '120'
-   * is green, '240' is blue. Numbers in between reflect different shades.
-   * The [saturationPercent] percentage; where'0' is the least and '100' is the
-   * greatest (100 represents full color).  The [lightnessPercent] percentage;
-   * where'0' is the least and '100' is the greatest.  The value 0 is dark or
-   * black, 100 is light or white and 50 is a medium lightness.
-   *
-   * If [alpha] is provided, it is the level of translucency which ranges from
-   * '0' (completely transparent foreground) to '1.0' (completely opaque
-   * foreground).
-   */
+  /// HSL takes three values.  The [hueDegree] degree on the color wheel; '0' is
+  /// the least and '100' is the greatest.  The value '0' or '360' is red, '120'
+  /// is green, '240' is blue. Numbers in between reflect different shades.
+  /// The [saturationPercent] percentage; where'0' is the least and '100' is the
+  /// greatest (100 represents full color).  The [lightnessPercent] percentage;
+  /// where'0' is the least and '100' is the greatest.  The value 0 is dark or
+  /// black, 100 is light or white and 50 is a medium lightness.
+  ///
+  /// If [alpha] is provided, it is the level of translucency which ranges from
+  /// '0' (completely transparent foreground) to '1.0' (completely opaque
+  /// foreground).
   Color.createHsla(num hueDegree, num saturationPercent, num lightnessPercent,
       [num alpha])
       : this._argb = new Hsla(
@@ -114,21 +94,19 @@
                 alpha != null ? Color._clamp(alpha, 0, 1) : alpha)
             .toHexArgbString();
 
-  /**
-   * The hslaRaw takes three values.  The [hue] degree on the color wheel; '0'
-   * is the least and '1' is the greatest.  The value '0' or '1' is red, the
-   * ratio of 120/360 is green, and the ratio of 240/360 is blue.  Numbers in
-   * between reflect different shades.  The [saturation] is a percentage; '0'
-   * is the least and '1' is the greatest.  The value of '1' is equivalent to
-   * 100% (full colour).  The [lightness] is a percentage; '0' is the least and
-   * '1' is the greatest.  The value of '0' is dark (black), the value of '1'
-   * is light (white), and the value of '.50' is a medium lightness.
-   *
-   * The fourth optional parameter is:
-   *   [alpha]      level of translucency range of values is 0..1, zero is a
-   *                completely transparent foreground and 1 is a completely
-   *                opaque foreground.
-   */
+  /// The hslaRaw takes three values.  The [hue] degree on the color wheel; '0'
+  /// is the least and '1' is the greatest.  The value '0' or '1' is red, the
+  /// ratio of 120/360 is green, and the ratio of 240/360 is blue.  Numbers in
+  /// between reflect different shades.  The [saturation] is a percentage; '0'
+  /// is the least and '1' is the greatest.  The value of '1' is equivalent to
+  /// 100% (full colour).  The [lightness] is a percentage; '0' is the least and
+  /// '1' is the greatest.  The value of '0' is dark (black), the value of '1'
+  /// is light (white), and the value of '.50' is a medium lightness.
+  ///
+  /// The fourth optional parameter is:
+  ///   [alpha]      level of translucency range of values is 0..1, zero is a
+  ///                completely transparent foreground and 1 is a completely
+  ///                opaque foreground.
   Color.hslaRaw(num hue, num saturation, num lightness, [num alpha])
       : this._argb = new Hsla(
                 Color._clamp(hue, 0, 1),
@@ -137,9 +115,7 @@
                 alpha != null ? Color._clamp(alpha, 0, 1) : alpha)
             .toHexArgbString();
 
-  /**
-   * Generate a real constant for pre-defined colors (no leading #).
-   */
+  /// Generate a real constant for pre-defined colors (no leading #).
   const Color.hex(this._argb);
 
   // TODO(jmesserly): this is needed by the example so leave it exposed for now.
@@ -237,11 +213,10 @@
   static const int _rgbaCss = 2;
   static const int _hslCss = 3;
   static const int _hslaCss = 4;
-  /**
-   * Parse CSS expressions of the from #rgb, rgb(r,g,b), rgba(r,g,b,a),
-   * hsl(h,s,l), hsla(h,s,l,a) and SVG colors (e.g., darkSlateblue, etc.) and
-   * convert to argb.
-   */
+
+  /// Parse CSS expressions of the from #rgb, rgb(r,g,b), rgba(r,g,b,a),
+  /// hsl(h,s,l), hsla(h,s,l,a) and SVG colors (e.g., darkSlateblue, etc.) and
+  /// convert to argb.
   static String _convertCssToArgb(String value) {
     // TODO(terry): Better parser/regex for converting CSS properties.
     String color = value.trim().replaceAll("\\s", "");
@@ -320,17 +295,15 @@
   static num _clamp(num value, num min, num max) =>
       math.max(math.min(max, value), min);
 
-  /**
-   * Change the tint (make color lighter) or shade (make color darker) of all
-   * parts of [rgba] (r, g and b).  The [amount] is percentage darker between
-   * -1 to 0 for darker and 0 to 1 for lighter; '0' is no change.  The [amount]
-   * will darken or lighten the rgb values; it will not change the alpha value.
-   * If [amount] is outside of the value -1 to +1 then [amount] is changed to
-   * either the min or max direction -1 or 1.
-   *
-   * Darker will approach the color #000000 (black) and lighter will approach
-   * the color #ffffff (white).
-   */
+  /// Change the tint (make color lighter) or shade (make color darker) of all
+  /// parts of [rgba] (r, g and b).  The [amount] is percentage darker between
+  /// -1 to 0 for darker and 0 to 1 for lighter; '0' is no change.  The [amount]
+  /// will darken or lighten the rgb values; it will not change the alpha value.
+  /// If [amount] is outside of the value -1 to +1 then [amount] is changed to
+  /// either the min or max direction -1 or 1.
+  ///
+  /// Darker will approach the color #000000 (black) and lighter will approach
+  /// the color #ffffff (white).
   static Rgba _createNewTintShadeFromRgba(Rgba rgba, num amount) {
     int r, g, b;
     num tintShade = Color._clamp(amount, -1, 1);
@@ -353,12 +326,10 @@
 
   // TODO(terry): This does an okay lighter/darker; better would be convert to
   //              HSL then change the lightness.
-  /**
-   * The parameter [v] is the color to change (r, g, or b) in the range '0' to
-   * '255'. The parameter [delta] is a number between '-1' and '1'.  A value
-   * between '-1' and '0' is darker and a value between '0' and '1' is lighter
-   * ('0' imples no change).
-   */
+  /// The parameter [v] is the color to change (r, g, or b) in the range '0' to
+  /// '255'. The parameter [delta] is a number between '-1' and '1'.  A value
+  /// between '-1' and '0' is darker and a value between '0' and '1' is lighter
+  /// ('0' imples no change).
   static num _changeTintShadeColor(num v, num delta) =>
       Color._clamp(((1 - delta) * v + (delta * 255)).round(), 0, 255);
 
@@ -513,9 +484,7 @@
   static final Color yellowGreen = const Color.hex("9acd32");
 }
 
-/**
- * Rgba class for users that want to interact with a color as a RGBA value.
- */
+/// Rgba class for users that want to interact with a color as a RGBA value.
 class Rgba implements _StyleProperty, ColorBase {
   // TODO(terry): Consider consolidating rgba to a single 32-bit int, make sure
   //              it works under JS and Dart VM.
@@ -635,24 +604,20 @@
   int get hashCode => toHexArgbString().hashCode;
 }
 
-/**
- * Hsl class support to interact with a color as a hsl with hue, saturation, and
- * lightness with optional alpha blending.  The hue is a ratio of 360 degrees
- * 360° = 1 or 0, (1° == (1/360)), saturation and lightness is a 0..1 fraction
- * (1 == 100%) and alpha is a 0..1 fraction.
- */
+/// Hsl class support to interact with a color as a hsl with hue, saturation,
+/// and lightness with optional alpha blending.  The hue is a ratio of 360
+/// degrees 360° = 1 or 0, (1° == (1/360)), saturation and lightness is a 0..1
+/// fraction (1 == 100%) and alpha is a 0..1 fraction.
 class Hsla implements _StyleProperty, ColorBase {
   final num _h; // Value from 0..1
   final num _s; // Value from 0..1
   final num _l; // Value from 0..1
   final num _a; // Value from 0..1
 
-  /**
-   * [hue] is a 0..1 fraction of 360 degrees (360 == 0).
-   * [saturation] is a 0..1 fraction (100% == 1).
-   * [lightness] is a 0..1 fraction (100% == 1).
-   * [alpha] is a 0..1 fraction, alpha blending between 0..1, 1 == 100% opaque.
-   */
+  /// [hue] is a 0..1 fraction of 360 degrees (360 == 0).
+  /// [saturation] is a 0..1 fraction (100% == 1).
+  /// [lightness] is a 0..1 fraction (100% == 1).
+  /// [alpha] is a 0..1 fraction, alpha blending between 0..1, 1 == 100% opaque.
   Hsla(num hue, num saturation, num lightness, [num alpha])
       : this._h = (hue == 1) ? 0 : Color._clamp(hue, 0, 1),
         this._s = Color._clamp(saturation, 0, 1),
@@ -730,39 +695,25 @@
     return new Hsla(h, s, l, a);
   }
 
-  /**
-   * Returns 0..1 fraction (ratio of 360°, e.g. 1° == 1/360).
-   */
+  /// Returns 0..1 fraction (ratio of 360°, e.g. 1° == 1/360).
   num get hue => _h;
 
-  /**
-   * Returns 0..1 fraction (1 == 100%)
-   */
+  /// Returns 0..1 fraction (1 == 100%)
   num get saturation => _s;
 
-  /**
-   * Returns 0..1 fraction (1 == 100%).
-   */
+  /// Returns 0..1 fraction (1 == 100%).
   num get lightness => _l;
 
-  /**
-   * Returns number as degrees 0..360.
-   */
+  /// Returns number as degrees 0..360.
   num get hueDegrees => (_h * 360).round();
 
-  /**
-   * Returns number as percentage 0..100
-   */
+  /// Returns number as percentage 0..100
   num get saturationPercentage => (_s * 100).round();
 
-  /**
-   * Returns number as percentage 0..100.
-   */
+  /// Returns number as percentage 0..100.
   num get lightnessPercentage => (_l * 100).round();
 
-  /**
-   * Returns number as 0..1
-   */
+  /// Returns number as 0..1
   num get alpha => _a;
 
   bool operator ==(other) => Color.equal(this, other);
@@ -787,7 +738,7 @@
   int get hashCode => toHexArgbString().hashCode;
 }
 
-/** X,Y position. */
+/// X,Y position.
 class PointXY implements _StyleProperty {
   final num x, y;
   const PointXY(this.x, this.y);
@@ -799,9 +750,7 @@
 }
 
 // TODO(terry): Implement style and color.
-/**
- * Supports border for measuring with layout.
- */
+/// Supports border for measuring with layout.
 class Border implements _StyleProperty {
   final int top, left, bottom, right;
 
@@ -823,39 +772,42 @@
   String get cssExpression {
     return (top == left && bottom == right && top == right)
         ? "${left}px"
-        : "${top != null ? '$top' : '0'}px ${right != null ? '$right' : '0'}px ${bottom != null ? '$bottom' : '0'}px ${left != null ? '$left' : '0'}px";
+        : "${top != null ? '$top' : '0'}px "
+        "${right != null ? '$right' : '0'}px "
+        "${bottom != null ? '$bottom' : '0'}px "
+        "${left != null ? '$left' : '0'}px";
   }
 }
 
-/** Font style constants. */
+/// Font style constants.
 class FontStyle {
-  /** Font style [normal] default. */
+  /// Font style [normal] default.
   static const String normal = "normal";
-  /**
-   * Font style [italic] use explicity crafted italic font otherwise inclined
-   * on the fly like oblique.
-   */
+
+  /// Font style [italic] use explicity crafted italic font otherwise inclined
+  /// on the fly like oblique.
   static const String italic = "italic";
-  /**
-   * Font style [oblique] is rarely used. The normal style of a font is inclined
-   * on the fly to the right by 8-12 degrees.
-   */
+
+  /// Font style [oblique] is rarely used. The normal style of a font is
+  /// inclined on the fly to the right by 8-12 degrees.
   static const String oblique = "oblique";
 }
 
-/** Font variant constants. */
+/// Font variant constants.
 class FontVariant {
-  /** Font style [normal] default. */
+  /// Font style [normal] default.
   static const String normal = "normal";
-  /** Font variant [smallCaps]. */
+
+  /// Font variant [smallCaps].
   static const String smallCaps = "small-caps";
 }
 
-/** Font weight constants values 100, 200, 300, 400, 500, 600, 700, 800, 900. */
+/// Font weight constants values 100, 200, 300, 400, 500, 600, 700, 800, 900.
 class FontWeight {
-  /** Font weight normal [default] */
+  /// Font weight normal [default]
   static const int normal = 400;
-  /** Font weight bold */
+
+  /// Font weight bold
   static const int bold = 700;
 
   static const int wt100 = 100;
@@ -869,73 +821,80 @@
   static const int wt900 = 900;
 }
 
-/** Generic font family names. */
+/// Generic font family names.
 class FontGeneric {
-  /** Generic family sans-serif font (w/o serifs). */
+  /// Generic family sans-serif font (w/o serifs).
   static const String sansSerif = "sans-serif";
-  /** Generic family serif font. */
+
+  /// Generic family serif font.
   static const String serif = "serif";
-  /** Generic family fixed-width font. */
+
+  /// Generic family fixed-width font.
   static const monospace = "monospace";
-  /** Generic family emulate handwriting font. */
+
+  /// Generic family emulate handwriting font.
   static const String cursive = "cursive";
-  /** Generic family decorative font. */
+
+  /// Generic family decorative font.
   static const String fantasy = "fantasy";
 }
 
-/**
- * List of most common font families across different platforms.  Use the
- * collection names in the Font class (e.g., Font.SANS_SERIF, Font.FONT_SERIF,
- * Font.MONOSPACE, Font.CURSIVE or Font.FANTASY).  These work best on all
- * platforms using the fonts that best match availability on each platform.
- * See <http://www.angelfire.com/al4/rcollins/style/fonts.html> for a good
- * description of fonts available between platforms and browsers.
- */
+/// List of most common font families across different platforms.  Use the
+/// collection names in the Font class (e.g., Font.SANS_SERIF, Font.FONT_SERIF,
+/// Font.MONOSPACE, Font.CURSIVE or Font.FANTASY).  These work best on all
+/// platforms using the fonts that best match availability on each platform.
+/// See <http://www.angelfire.com/al4/rcollins/style/fonts.html> for a good
+/// description of fonts available between platforms and browsers.
 class FontFamily {
-  /** Sans-Serif font for Windows similar to Helvetica on Mac bold/italic. */
+  /// Sans-Serif font for Windows similar to Helvetica on Mac bold/italic.
   static const String arial = "arial";
-  /** Sans-Serif font for Windows less common already bolded. */
+
+  /// Sans-Serif font for Windows less common already bolded.
   static const String arialBlack = "arial black";
-  /** Sans-Serif font for Mac since 1984, similar to Arial/Helvetica. */
+
+  /// Sans-Serif font for Mac since 1984, similar to Arial/Helvetica.
   static const String geneva = "geneva";
-  /** Sans-Serif font for Windows most readable sans-serif font for displays. */
+
+  /// Sans-Serif font for Windows most readable sans-serif font for displays.
   static const String verdana = "verdana";
-  /** Sans-Serif font for Mac since 1984 is identical to Arial. */
+
+  /// Sans-Serif font for Mac since 1984 is identical to Arial.
   static const String helvetica = "helvetica";
 
-  /** Serif font for Windows traditional font with “old-style” numerals. */
+  /// Serif font for Windows traditional font with “old-style” numerals.
   static const String georgia = "georgia";
-  /**
-   * Serif font for Mac. PCs may have the non-scalable Times use Times New
-   * Roman instead.  Times is more compact than Times New Roman.
-   */
+
+  /// Serif font for Mac. PCs may have the non-scalable Times use Times New
+  /// Roman instead.  Times is more compact than Times New Roman.
   static const String times = "times";
-  /**
-   * Serif font for Windows most common serif font and default serif font for
-   * most browsers.
-   */
+
+  /// Serif font for Windows most common serif font and default serif font for
+  /// most browsers.
   static const String timesNewRoman = "times new roman";
 
-  /**
-   * Monospace font for Mac/Windows most common. Scalable on Mac not scalable
-   * on Windows.
-   */
+  /// Monospace font for Mac/Windows most common. Scalable on Mac not scalable
+  /// on Windows.
   static const String courier = "courier";
-  /** Monospace font for Mac/Windows scalable on both platforms. */
+
+  /// Monospace font for Mac/Windows scalable on both platforms.
   static const String courierNew = "courier new";
 
-  /** Cursive font for Windows and default cursive font for IE. */
+  /// Cursive font for Windows and default cursive font for IE.
   static const String comicSansMs = "comic sans ms";
-  /** Cursive font for Mac on Macs 2000 and newer. */
+
+  /// Cursive font for Mac on Macs 2000 and newer.
   static const String textile = "textile";
-  /** Cursive font for older Macs. */
+
+  /// Cursive font for older Macs.
   static const String appleChancery = "apple chancery";
-  /** Cursive font for some PCs. */
+
+  /// Cursive font for some PCs.
   static const String zaphChancery = "zaph chancery";
 
-  /** Fantasy font on most Mac/Windows/Linux platforms. */
+  /// Fantasy font on most Mac/Windows/Linux platforms.
   static const String impact = "impact";
-  /** Fantasy font for Windows. */
+
+  /// Fantasy font for Windows.
   static const String webdings = "webdings";
 }
 
@@ -946,11 +905,9 @@
 }
 
 // TODO(terry): Support @font-face fule.
-/**
- * Font style support for size, family, weight, style, variant, and lineheight.
- */
+/// Font style support for size, family, weight, style, variant, and lineheight.
 class Font implements _StyleProperty {
-  /** Collection of most common sans-serif fonts in order. */
+  /// Collection of most common sans-serif fonts in order.
   static const List<String> sansSerif = const [
     FontFamily.arial,
     FontFamily.verdana,
@@ -959,27 +916,30 @@
     FontGeneric.sansSerif
   ];
 
-  /** Collection of most common serif fonts in order. */
+  /// Collection of most common serif fonts in order.
   static const List<String> serif = const [
     FontFamily.georgia,
     FontFamily.timesNewRoman,
     FontFamily.times,
     FontGeneric.serif
   ];
-  /** Collection of most common monospace fonts in order. */
+
+  /// Collection of most common monospace fonts in order.
   static const List<String> monospace = const [
     FontFamily.courierNew,
     FontFamily.courier,
     FontGeneric.monospace
   ];
-  /** Collection of most common cursive fonts in order. */
+
+  /// Collection of most common cursive fonts in order.
   static const List<String> cursive = const [
     FontFamily.textile,
     FontFamily.appleChancery,
     FontFamily.zaphChancery,
     FontGeneric.fantasy
   ];
-  /** Collection of most common fantasy fonts in order. */
+
+  /// Collection of most common fantasy fonts in order.
   static const List<String> fantasy = const [
     FontFamily.comicSansMs,
     FontFamily.impact,
@@ -989,30 +949,26 @@
 
   // TODO(terry): Should support the values xx-small, small, large, xx-large,
   //              etc. (mapped to a pixel sized font)?
-  /** Font size in pixels. */
+  /// Font size in pixels.
   final num size;
 
   // TODO(terry): _family should be an immutable list, wrapper class to do this
   //              should exist in Dart.
-  /**
-   * Family specifies a list of fonts, the browser will sequentially select the
-   * the first known/supported font.  There are two types of font families the
-   * family-name (e.g., arial, times, courier, etc) or the generic-family (e.g.,
-   * serif, sans-seric, etc.)
-   */
+  /// Family specifies a list of fonts, the browser will sequentially select the
+  /// the first known/supported font.  There are two types of font families the
+  /// family-name (e.g., arial, times, courier, etc) or the generic-family
+  /// (e.g., serif, sans-seric, etc.)
   final List<String> family;
 
-  /** Font weight from 100, 200, 300, 400, 500, 600, 700, 800, 900 */
+  /// Font weight from 100, 200, 300, 400, 500, 600, 700, 800, 900
   final int weight;
 
-  /** Style of a font normal, italic, oblique. */
+  /// Style of a font normal, italic, oblique.
   final String style;
 
-  /**
-   * Font variant NORMAL (default) or SMALL_CAPS.  Different set of font glyph
-   * lower case letters designed to have to fit within the font-height and
-   * weight of the corresponding lowercase letters.
-   */
+  /// Font variant NORMAL (default) or SMALL_CAPS.  Different set of font glyph
+  /// lower case letters designed to have to fit within the font-height and
+  /// weight of the corresponding lowercase letters.
   final String variant;
 
   final LineHeight lineHeight;
@@ -1028,12 +984,10 @@
   // height.  Classic typography suggest the ratio be 1.5.  See
   // <http://www.pearsonified.com/2011/12/golden-ratio-typography.php> and
   // <http://meyerweb.com/eric/thoughts/2008/05/06/line-height-abnormal/>.
-  /**
-   * Create a font using [size] of font in pixels, [family] name of font(s)
-   * using [FontFamily], [style] of the font using [FontStyle], [variant] using
-   * [FontVariant], and [lineHeight] extra space (leading) around the font in
-   * pixels, if not specified it's 1.2 the font size.
-   */
+  /// Create a font using [size] of font in pixels, [family] name of font(s)
+  /// using [FontFamily], [style] of the font using [FontStyle], [variant] using
+  /// [FontVariant], and [lineHeight] extra space (leading) around the font in
+  /// pixels, if not specified it's 1.2 the font size.
   const Font(
       {this.size,
       this.family,
@@ -1042,10 +996,8 @@
       this.variant,
       this.lineHeight});
 
-  /**
-   * Merge the two fonts and return the result. See [Style.merge] for
-   * more information.
-   */
+  /// Merge the two fonts and return the result. See [Style.merge] for
+  /// more information.
   factory Font.merge(Font a, Font b) {
     if (a == null) return b;
     if (b == null) return a;
@@ -1060,14 +1012,12 @@
         variant = _mergeVal(a.variant, b.variant),
         lineHeight = _mergeVal(a.lineHeight, b.lineHeight);
 
-  /**
-   * Shorthand CSS format for font is:
-   *
-   *    font-style font-variant font-weight font-size/line-height font-family
-   *
-   * The font-size and font-family values are required. If any of the other
-   * values are missing the default value is used.
-   */
+  /// Shorthand CSS format for font is:
+  ///
+  ///    font-style font-variant font-weight font-size/line-height font-family
+  ///
+  /// The font-size and font-family values are required. If any of the other
+  /// values are missing the default value is used.
   String get cssExpression {
     // TODO(jimhug): include variant, style, other options
     if (weight != null) {
@@ -1088,15 +1038,13 @@
       style: style,
       variant: variant);
 
-  /**
-   * The lineHeight, provides an indirect means to specify the leading. The
-   * leading is the difference between the font-size height and the (used)
-   * value of line height in pixels.  If lineHeight is not specified it's
-   * automatically computed as 1.2 of the font size.  Firefox is 1.2, Safari is
-   * ~1.2, and CSS suggest a ration from 1 to 1.2 of the font-size when
-   * computing line-height. The Font class constructor has the computation for
-   * _lineHeight.
-   */
+  /// The lineHeight, provides an indirect means to specify the leading. The
+  /// leading is the difference between the font-size height and the (used)
+  /// value of line height in pixels.  If lineHeight is not specified it's
+  /// automatically computed as 1.2 of the font size.  Firefox is 1.2, Safari is
+  /// ~1.2, and CSS suggest a ration from 1 to 1.2 of the font-size when
+  /// computing line-height. The Font class constructor has the computation for
+  /// _lineHeight.
   num get lineHeightInPixels {
     if (lineHeight != null) {
       if (lineHeight.inPixels) {
@@ -1127,66 +1075,56 @@
 
   // TODO(terry): This is fragile should probably just iterate through the list
   //              of fonts construction the font-family string.
-  /** Return fonts as a comma seperated list sans the square brackets. */
+  /// Return fonts as a comma seperated list sans the square brackets.
   String get _fontsAsString {
     String fonts = family.toString();
     return fonts.length > 2 ? fonts.substring(1, fonts.length - 1) : "";
   }
 }
 
-/**
- * This class stores the sizes of the box edges in the CSS [box model][]. Each
- * edge area is placed around the sides of the content box. The innermost area
- * is the [Style.padding] area which has a background and surrounds the content.
- * The content and padding area is surrounded by the [Style.border], which
- * itself is surrounded by the transparent [Style.margin]. This box represents
- * the eges of padding, border, or margin depending on which accessor was used
- * to retrieve it.
- *
- * [box model]: https://developer.mozilla.org/en/CSS/box_model
- */
+/// This class stores the sizes of the box edges in the CSS [box model][]. Each
+/// edge area is placed around the sides of the content box. The innermost area
+/// is the [Style.padding] area which has a background and surrounds the
+/// content.  The content and padding area is surrounded by the [Style.border],
+/// which itself is surrounded by the transparent [Style.margin]. This box
+/// represents the eges of padding, border, or margin depending on which
+/// accessor was used to retrieve it.
+///
+/// [box model]: https://developer.mozilla.org/en/CSS/box_model
 class BoxEdge {
-  /** The size of the left edge, or null if the style has no edge. */
+  /// The size of the left edge, or null if the style has no edge.
   final num left;
 
-  /** The size of the top edge, or null if the style has no edge. */
+  /// The size of the top edge, or null if the style has no edge.
   final num top;
 
-  /** The size of the right edge, or null if the style has no edge. */
+  /// The size of the right edge, or null if the style has no edge.
   final num right;
 
-  /** The size of the bottom edge, or null if the style has no edge. */
+  /// The size of the bottom edge, or null if the style has no edge.
   final num bottom;
 
-  /**
-   * Creates a box edge with the specified [left], [top], [right], and
-   * [bottom] width.
-   */
+  /// Creates a box edge with the specified [left], [top], [right], and
+  /// [bottom] width.
   const BoxEdge([this.left, this.top, this.right, this.bottom]);
 
-  /**
-   * Creates a box edge with the specified [top], [right], [bottom], and
-   * [left] width. This matches the typical CSS order:
-   * <https://developer.mozilla.org/en/CSS/margin>
-   * <https://developer.mozilla.org/en/CSS/border-width>
-   * <https://developer.mozilla.org/en/CSS/padding>.
-   */
+  /// Creates a box edge with the specified [top], [right], [bottom], and
+  /// [left] width. This matches the typical CSS order:
+  /// <https://developer.mozilla.org/en/CSS/margin>
+  /// <https://developer.mozilla.org/en/CSS/border-width>
+  /// <https://developer.mozilla.org/en/CSS/padding>.
   const BoxEdge.clockwiseFromTop(this.top, this.right, this.bottom, this.left);
 
-  /**
-   * This is a helper to creates a box edge with the same [left], [top]
-   * [right], and [bottom] widths.
-   */
+  /// This is a helper to creates a box edge with the same [left], [top]
+  /// [right], and [bottom] widths.
   const BoxEdge.uniform(num size)
       : top = size,
         left = size,
         bottom = size,
         right = size;
 
-  /**
-   * Takes a possibly null box edge, with possibly null metrics, and fills
-   * them in with 0 instead.
-   */
+  /// Takes a possibly null box edge, with possibly null metrics, and fills
+  /// them in with 0 instead.
   factory BoxEdge.nonNull(BoxEdge other) {
     if (other == null) return const BoxEdge(0, 0, 0, 0);
     num left = other.left;
@@ -1213,10 +1151,8 @@
     return make ? new BoxEdge(left, top, right, bottom) : other;
   }
 
-  /**
-   * Merge the two box edge sizes and return the result. See [Style.merge] for
-   * more information.
-   */
+  /// Merge the two box edge sizes and return the result. See [Style.merge] for
+  /// more information.
   factory BoxEdge.merge(BoxEdge x, BoxEdge y) {
     if (x == null) return y;
     if (y == null) return x;
@@ -1229,16 +1165,12 @@
         right = _mergeVal(x.right, y.right),
         bottom = _mergeVal(x.bottom, y.bottom);
 
-  /**
-   * The total size of the horizontal edges. Equal to [left] + [right], where
-   * null is interpreted as 0px.
-   */
+  /// The total size of the horizontal edges. Equal to [left] + [right], where
+  /// null is interpreted as 0px.
   num get width => (left != null ? left : 0) + (right != null ? right : 0);
 
-  /**
-   * The total size of the vertical edges. Equal to [top] + [bottom], where
-   * null is interpreted as 0px.
-   */
+  /// The total size of the vertical edges. Equal to [top] + [bottom], where
+  /// null is interpreted as 0px.
   num get height => (top != null ? top : 0) + (bottom != null ? bottom : 0);
 }
 
diff --git a/lib/src/token.dart b/lib/src/token.dart
index e30484d..873c217 100644
--- a/lib/src/token.dart
+++ b/lib/src/token.dart
@@ -4,28 +4,26 @@
 
 part of csslib.parser;
 
-/**
- * A single token in the Dart language.
- */
+/// A single token in the Dart language.
 class Token {
-  /** A member of [TokenKind] specifying what kind of token this is. */
+  /// A member of [TokenKind] specifying what kind of token this is.
   final int kind;
 
-  /** The location where this token was parsed from. */
+  /// The location where this token was parsed from.
   final FileSpan span;
 
-  /** The start offset of this token. */
+  /// The start offset of this token.
   int get start => span.start.offset;
 
-  /** The end offset of this token. */
+  /// The end offset of this token.
   int get end => span.end.offset;
 
-  /** Returns the source text corresponding to this [Token]. */
+  /// Returns the source text corresponding to this [Token].
   String get text => span.text;
 
   Token(this.kind, this.span);
 
-  /** Returns a pretty representation of this token for error messages. **/
+  /// Returns a pretty representation of this token for error messages.
   String toString() {
     var kindText = TokenKind.kindToString(kind);
     var actualText = text.trim();
@@ -40,24 +38,22 @@
   }
 }
 
-/** A token containing a parsed literal value. */
+/// A token containing a parsed literal value.
 class LiteralToken extends Token {
   var value;
   LiteralToken(int kind, FileSpan span, this.value) : super(kind, span);
 }
 
-/** A token containing error information. */
+/// A token containing error information.
 class ErrorToken extends Token {
   String message;
   ErrorToken(int kind, FileSpan span, this.message) : super(kind, span);
 }
 
-/**
- * CSS ident-token.
- *
- * See <http://dev.w3.org/csswg/css-syntax/#typedef-ident-token> and
- * <http://dev.w3.org/csswg/css-syntax/#ident-token-diagram>.
- */
+/// CSS ident-token.
+///
+/// See <http://dev.w3.org/csswg/css-syntax/#typedef-ident-token> and
+/// <http://dev.w3.org/csswg/css-syntax/#ident-token-diagram>.
 class IdentifierToken extends Token {
   final String text;
 
diff --git a/lib/src/tokenizer.dart b/lib/src/tokenizer.dart
index 0b0661a..f5f4fbd 100644
--- a/lib/src/tokenizer.dart
+++ b/lib/src/tokenizer.dart
@@ -5,14 +5,14 @@
 part of csslib.parser;
 
 class Tokenizer extends TokenizerBase {
-  /** U+ prefix for unicode characters. */
+  /// U+ prefix for unicode characters.
   final UNICODE_U = 'U'.codeUnitAt(0);
   final UNICODE_LOWER_U = 'u'.codeUnitAt(0);
   final UNICODE_PLUS = '+'.codeUnitAt(0);
 
   final QUESTION_MARK = '?'.codeUnitAt(0);
 
-  /** CDATA keyword. */
+  /// CDATA keyword.
   final List CDATA_NAME = 'CDATA'.codeUnits;
 
   Tokenizer(SourceFile file, String text, bool skipWhitespace, [int index = 0])
@@ -431,7 +431,7 @@
   }
 }
 
-/** Static helper methods. */
+/// Static helper methods.
 class TokenizerHelpers {
   static bool isIdentifierStart(int c) {
     return isIdentifierStartExpr(c) || c == 45 /*-*/;
@@ -451,7 +451,7 @@
     return isIdentifierPartExpr(c) || c == 45 /*-*/;
   }
 
-  /** Pseudo function expressions identifiers can't have a minus sign. */
+  /// Pseudo function expressions identifiers can't have a minus sign.
   static bool isIdentifierStartExpr(int c) {
     return ((c >= 97 /*a*/ && c <= 122 /*z*/) ||
         (c >= 65 /*A*/ && c <= 90 /*Z*/) ||
@@ -464,7 +464,7 @@
         c == 92 /*\*/);
   }
 
-  /** Pseudo function expressions identifiers can't have a minus sign. */
+  /// Pseudo function expressions identifiers can't have a minus sign.
   static bool isIdentifierPartExpr(int c) {
     return (isIdentifierStartExpr(c) || isDigit(c));
   }
diff --git a/lib/src/tokenizer_base.dart b/lib/src/tokenizer_base.dart
index c2a448f..07aee79 100644
--- a/lib/src/tokenizer_base.dart
+++ b/lib/src/tokenizer_base.dart
@@ -5,7 +5,7 @@
 
 part of csslib.parser;
 
-/** Tokenizer state to support look ahead for Less' nested selectors. */
+/// Tokenizer state to support look ahead for Less' nested selectors.
 class TokenizerState {
   final int index;
   final int startIndex;
@@ -19,27 +19,21 @@
         inSelector = base.inSelector;
 }
 
-/**
- * The base class for our tokenizer. The hand coded parts are in this file, with
- * the generated parts in the subclass Tokenizer.
- */
+/// The base class for our tokenizer. The hand coded parts are in this file,
+/// with the generated parts in the subclass Tokenizer.
 abstract class TokenizerBase {
   final SourceFile _file;
   final String _text;
 
   bool _inString;
 
-  /**
-   * Changes tokenization when in a pseudo function expression.  If true then
-   * minus signs are handled as operators instead of identifiers.
-   */
+  /// Changes tokenization when in a pseudo function expression.  If true then
+  /// minus signs are handled as operators instead of identifiers.
   bool inSelectorExpression = false;
 
-  /**
-   * Changes tokenization when in selectors. If true, it prevents identifiers
-   * from being treated as units. This would break things like ":lang(fr)" or
-   * the HTML (unknown) tag name "px", which is legal to use in a selector.
-   */
+  /// Changes tokenization when in selectors. If true, it prevents identifiers
+  /// from being treated as units. This would break things like ":lang(fr)" or
+  /// the HTML (unknown) tag name "px", which is legal to use in a selector.
   // TODO(jmesserly): is this a problem elsewhere? "fr" for example will be
   // processed as a "fraction" unit token, preventing it from working in
   // places where an identifier is expected. This was breaking selectors like:
@@ -60,10 +54,10 @@
   Token next();
   int getIdentifierKind();
 
-  /** Snapshot of Tokenizer scanning state. */
+  /// Snapshot of Tokenizer scanning state.
   TokenizerState get mark => new TokenizerState(this);
 
-  /** Restore Tokenizer scanning state. */
+  /// Restore Tokenizer scanning state.
   void restore(TokenizerState markedData) {
     _index = markedData.index;
     _startIndex = markedData.startIndex;
diff --git a/lib/src/tokenkind.dart b/lib/src/tokenkind.dart
index 14cf3c9..1afbe4e 100644
--- a/lib/src/tokenkind.dart
+++ b/lib/src/tokenkind.dart
@@ -51,28 +51,28 @@
   //          character in the TokenChar list at the bottom of this file.  The
   //          order of the above tokens should be the same order as TokenChar.
 
-  /** [TokenKind] representing integer tokens. */
+  /// [TokenKind] representing integer tokens.
   static const int INTEGER = 60;
 
-  /** [TokenKind] representing hex integer tokens. */
+  /// [TokenKind] representing hex integer tokens.
   static const int HEX_INTEGER = 61;
 
-  /** [TokenKind] representing double tokens. */
+  /// [TokenKind] representing double tokens.
   static const int DOUBLE = 62;
 
-  /** [TokenKind] representing whitespace tokens. */
+  /// [TokenKind] representing whitespace tokens.
   static const int WHITESPACE = 63;
 
-  /** [TokenKind] representing comment tokens. */
+  /// [TokenKind] representing comment tokens.
   static const int COMMENT = 64;
 
-  /** [TokenKind] representing error tokens. */
+  /// [TokenKind] representing error tokens.
   static const int ERROR = 65;
 
-  /** [TokenKind] representing incomplete string tokens. */
+  /// [TokenKind] representing incomplete string tokens.
   static const int INCOMPLETE_STRING = 66;
 
-  /** [TokenKind] representing incomplete comment tokens. */
+  /// [TokenKind] representing incomplete comment tokens.
   static const int INCOMPLETE_COMMENT = 67;
 
   static const int VAR_DEFINITION = 400; // var-NNN-NNN
@@ -477,10 +477,8 @@
   //              see http://www.w3schools.com/cssref/pr_list-style-type.asp
   //              for list of possible values.
 
-  /**
-   * Check if name is a pre-defined CSS name.  Used by error handler to report
-   * if name is unknown or used improperly.
-   */
+  /// Check if name is a pre-defined CSS name.  Used by error handler to report
+  /// if name is unknown or used improperly.
   static bool isPredefinedName(String name) {
     var nameLen = name.length;
     // TODO(terry): Add more pre-defined names (hidden, bolder, inherit, etc.).
@@ -494,7 +492,7 @@
     return true;
   }
 
-  /** Return the token that matches the unit ident found. */
+  /// Return the token that matches the unit ident found.
   static int matchList(
       var identList, String tokenField, String text, int offset, int length) {
     for (final entry in identList) {
@@ -526,22 +524,22 @@
     return -1; // Not a unit token.
   }
 
-  /** Return the token that matches the unit ident found. */
+  /// Return the token that matches the unit ident found.
   static int matchUnits(String text, int offset, int length) {
     return matchList(_UNITS, 'unit', text, offset, length);
   }
 
-  /** Return the token that matches the directive name found. */
+  /// Return the token that matches the directive name found.
   static int matchDirectives(String text, int offset, int length) {
     return matchList(_DIRECTIVES, 'type', text, offset, length);
   }
 
-  /** Return the token that matches the margin directive name found. */
+  /// Return the token that matches the margin directive name found.
   static int matchMarginDirectives(String text, int offset, int length) {
     return matchList(MARGIN_DIRECTIVES, 'type', text, offset, length);
   }
 
-  /** Return the token that matches the media operator found. */
+  /// Return the token that matches the media operator found.
   static int matchMediaOperator(String text, int offset, int length) {
     return matchList(MEDIA_OPERATORS, 'type', text, offset, length);
   }
@@ -556,7 +554,7 @@
     return null;
   }
 
-  /** Return the unit token as its pretty name. */
+  /// Return the unit token as its pretty name.
   static String unitToString(int unitTokenToFind) {
     if (unitTokenToFind == TokenKind.PERCENT) {
       return '%';
@@ -572,17 +570,15 @@
     return '<BAD UNIT>'; // Not a unit token.
   }
 
-  /**
-   * Match color name, case insensitive match and return the associated color
-   * entry from _EXTENDED_COLOR_NAMES list, return [:null:] if not found.
-   */
+  /// Match color name, case insensitive match and return the associated color
+  /// entry from _EXTENDED_COLOR_NAMES list, return [:null:] if not found.
   static Map matchColorName(String text) {
     var name = text.toLowerCase();
     return _EXTENDED_COLOR_NAMES.firstWhere((e) => e['name'] == name,
         orElse: () => null);
   }
 
-  /** Return RGB value as [int] from a color entry in _EXTENDED_COLOR_NAMES. */
+  /// Return RGB value as [int] from a color entry in _EXTENDED_COLOR_NAMES.
   static int colorValue(Map entry) {
     assert(entry != null);
     return entry['value'];
diff --git a/lib/src/tree.dart b/lib/src/tree.dart
index 70b64c8..8769866 100644
--- a/lib/src/tree.dart
+++ b/lib/src/tree.dart
@@ -105,7 +105,7 @@
 }
 
 class SimpleSelectorSequence extends TreeNode {
-  /** +, >, ~, NONE */
+  /// +, >, ~, NONE
   int combinator;
   final SimpleSelector simpleSelector;
 
@@ -151,9 +151,8 @@
   String toString() => simpleSelector.name;
 }
 
-/* All other selectors (element, #id, .class, attribute, pseudo, negation,
- * namespace, *) are derived from this selector.
- */
+// All other selectors (element, #id, .class, attribute, pseudo, negation,
+// namespace, *) are derived from this selector.
 abstract class SimpleSelector extends TreeNode {
   final _name; // Wildcard, ThisOperator, Identifier, Negation, others?
 
@@ -378,9 +377,7 @@
 }
 
 class StyleSheet extends TreeNode {
-  /**
-   * Contains charset, ruleset, directives (media, page, etc.), and selectors.
-   */
+  /// Contains charset, ruleset, directives (media, page, etc.), and selectors.
   final List<TreeNode> topLevels;
 
   StyleSheet(this.topLevels, SourceSpan span) : super(span) {
@@ -389,7 +386,7 @@
     }
   }
 
-  /** Selectors only in this tree. */
+  /// Selectors only in this tree.
   StyleSheet.selector(this.topLevels, SourceSpan span) : super(span);
 
   StyleSheet clone() {
@@ -554,10 +551,10 @@
 }
 
 class ImportDirective extends Directive {
-  /** import name specified. */
+  /// import name specified.
   final String import;
 
-  /** Any media queries for this import. */
+  /// Any media queries for this import.
   final List<MediaQuery> mediaQueries;
 
   ImportDirective(this.import, this.mediaQueries, SourceSpan span)
@@ -574,10 +571,9 @@
   visit(VisitorBase visitor) => visitor.visitImportDirective(this);
 }
 
-/**
- *  MediaExpression grammar:
- *    '(' S* media_feature S* [ ':' S* expr ]? ')' S*
- */
+/// MediaExpression grammar:
+///
+///     '(' S* media_feature S* [ ':' S* expr ]? ')' S*
 class MediaExpression extends TreeNode {
   final bool andOperator;
   final Identifier _mediaFeature;
@@ -597,19 +593,18 @@
   visit(VisitorBase visitor) => visitor.visitMediaExpression(this);
 }
 
-/**
- * MediaQuery grammar:
- *    : [ONLY | NOT]? S* media_type S* [ AND S* media_expression ]*
- *    | media_expression [ AND S* media_expression ]*
- *   media_type
- *    : IDENT
- *   media_expression
- *    : '(' S* media_feature S* [ ':' S* expr ]? ')' S*
- *   media_feature
- *    : IDENT
- */
+/// MediaQuery grammar:
+///
+///      : [ONLY | NOT]? S* media_type S* [ AND S* media_expression ]*
+///      | media_expression [ AND S* media_expression ]*
+///     media_type
+///      : IDENT
+///     media_expression
+///      : '(' S* media_feature S* [ ':' S* expr ]? ')' S*
+///     media_feature
+///      : IDENT
 class MediaQuery extends TreeNode {
-  /** not, only or no operator. */
+  /// not, only or no operator.
   final int _mediaUnary;
   final Identifier _mediaType;
   final List<MediaExpression> expressions;
@@ -705,9 +700,7 @@
 }
 
 class KeyFrameDirective extends Directive {
-  /*
-   * Either @keyframe or keyframe prefixed with @-webkit-, @-moz-, @-ms-, @-o-.
-   */
+  // Either @keyframe or keyframe prefixed with @-webkit-, @-moz-, @-ms-, @-o-.
   final int _keyframeName;
   final Identifier name;
   final List<KeyFrameBlock> _blocks;
@@ -790,10 +783,10 @@
 }
 
 class NamespaceDirective extends Directive {
-  /** Namespace prefix. */
+  /// Namespace prefix.
   final String _prefix;
 
-  /** URI associated with this namespace. */
+  /// URI associated with this namespace.
   final String _uri;
 
   NamespaceDirective(this._prefix, this._uri, SourceSpan span) : super(span);
@@ -805,7 +798,7 @@
   String get prefix => _prefix.length > 0 ? '$_prefix ' : '';
 }
 
-/** To support Less syntax @name: expression */
+/// To support Less syntax @name: expression
 class VarDefinitionDirective extends Directive {
   final VarDefinition def;
 
@@ -836,7 +829,7 @@
   visit(VisitorBase visitor) => visitor.visitMixinDefinition(this);
 }
 
-/** Support a Sass @mixin. See http://sass-lang.com for description. */
+/// Support a Sass @mixin. See http://sass-lang.com for description.
 class MixinRulesetDirective extends MixinDefinition {
   final List<TreeNode> rulesets;
 
@@ -879,7 +872,7 @@
   visit(VisitorBase visitor) => visitor.visitMixinDeclarationDirective(this);
 }
 
-/** To support consuming a SASS mixin @include. */
+/// To support consuming a Sass mixin @include.
 class IncludeDirective extends Directive {
   final String name;
   final List<List<Expression>> args;
@@ -897,7 +890,7 @@
   visit(VisitorBase visitor) => visitor.visitIncludeDirective(this);
 }
 
-/** To support SASS @content. */
+/// To support Sass @content.
 class ContentDirective extends Directive {
   ContentDirective(SourceSpan span) : super(span);
 
@@ -907,18 +900,17 @@
 class Declaration extends TreeNode {
   final Identifier _property;
   final Expression _expression;
-  /** Style exposed to Dart. */
+  /// Style exposed to Dart.
   dynamic dartStyle;
   final bool important;
 
-  /**
-   * IE CSS hacks that can only be read by a particular IE version.
-   *   7 implies IE 7 or older property (e.g., *background: blue;)
-   *   Note:  IE 8 or older property (e.g., background: green\9;) is handled
-   *          by IE8Term in declaration expression handling.
-   *   Note:  IE 6 only property with a leading underscore is a valid IDENT
-   *          since an ident can start with underscore (e.g., _background: red;)
-   */
+  /// IE CSS hacks that can only be read by a particular IE version.
+  /// 7 implies IE 7 or older property (e.g., `*background: blue;`)
+  ///
+  /// * Note:  IE 8 or older property (e.g., `background: green\9;`) is handled
+  ///   by IE8Term in declaration expression handling.
+  /// * Note:  IE 6 only property with a leading underscore is a valid IDENT
+  ///   since an ident can start with underscore (e.g., `_background: red;`)
   final bool isIE7;
 
   Declaration(this._property, this._expression, this.dartStyle, SourceSpan span,
@@ -959,13 +951,12 @@
   visit(VisitorBase visitor) => visitor.visitVarDefinition(this);
 }
 
-/**
- * Node for usage of @include mixin[(args,...)] found in a declaration group
- * instead of at a ruleset (toplevel) e.g.,
- * div {
- *   @include mixin1;
- * }
- */
+/// Node for usage of @include mixin[(args,...)] found in a declaration group
+/// instead of at a ruleset (toplevel) e.g.,
+///
+///     div {
+///       @include mixin1;
+///     }
 class IncludeMixinAtDeclaration extends Declaration {
   final IncludeDirective include;
 
@@ -993,7 +984,7 @@
 }
 
 class DeclarationGroup extends TreeNode {
-  /** Can be either Declaration or RuleSet (if nested selector). */
+  /// Can be either Declaration or RuleSet (if nested selector).
   final List<TreeNode> declarations;
 
   DeclarationGroup(this.declarations, SourceSpan span) : super(span);
@@ -1238,7 +1229,7 @@
   visit(VisitorBase visitor) => visitor.visitViewportTerm(this);
 }
 
-/** Type to signal a bad hex value for HexColorTerm.value. */
+/// Type to signal a bad hex value for HexColorTerm.value.
 class BAD_HEX_VALUE {}
 
 class HexColorTerm extends LiteralTerm {
@@ -1258,11 +1249,9 @@
   visit(VisitorBase visitor) => visitor.visitFunctionTerm(this);
 }
 
-/**
- * A "\9" was encountered at the end of the expression and before a semi-colon.
- * This is an IE trick to ignore a property or value except by IE 8 and older
- * browsers.
- */
+/// A "\9" was encountered at the end of the expression and before a semi-colon.
+/// This is an IE trick to ignore a property or value except by IE 8 and older
+/// browsers.
 class IE8Term extends LiteralTerm {
   IE8Term(SourceSpan span) : super('\\9', '\\9', span);
   IE8Term clone() => new IE8Term(span);
@@ -1347,11 +1336,9 @@
 
   DartStyleExpression(this._styleType, SourceSpan span) : super(span);
 
-  /*
-   * Merges give 2 DartStyleExpression (or derived from DartStyleExpression,
-   * e.g., FontExpression, etc.) will merge if the two expressions are of the
-   * same property name (implies same exact type e.g, FontExpression).
-   */
+  // Merges give 2 DartStyleExpression (or derived from DartStyleExpression,
+  // e.g., FontExpression, etc.) will merge if the two expressions are of the
+  // same property name (implies same exact type e.g, FontExpression).
   merged(DartStyleExpression newDartExpr);
 
   bool get isUnknown => _styleType == 0 || _styleType == null;
@@ -1397,9 +1384,7 @@
     return null;
   }
 
-  /**
-   * Merge the two FontExpression and return the result.
-   */
+  /// Merge the two FontExpression and return the result.
   factory FontExpression.merge(FontExpression x, FontExpression y) {
     return new FontExpression._merge(x, y, y.span);
   }
@@ -1442,7 +1427,7 @@
 
 class MarginExpression extends BoxExpression {
   // TODO(terry): Does auto for margin need to be exposed to Dart UI framework?
-  /** Margin expression ripped apart. */
+  /// Margin expression ripped apart.
   MarginExpression(SourceSpan span, {num top, num right, num bottom, num left})
       : super(DartStyleExpression.marginStyle, span,
             new BoxEdge(left, top, right, bottom));
@@ -1460,9 +1445,7 @@
     return null;
   }
 
-  /**
-   * Merge the two MarginExpressions and return the result.
-   */
+  /// Merge the two MarginExpressions and return the result.
   factory MarginExpression.merge(MarginExpression x, MarginExpression y) {
     return new MarginExpression._merge(x, y, y.span);
   }
@@ -1478,7 +1461,7 @@
 }
 
 class BorderExpression extends BoxExpression {
-  /** Border expression ripped apart. */
+  /// Border expression ripped apart.
   BorderExpression(SourceSpan span, {num top, num right, num bottom, num left})
       : super(DartStyleExpression.borderStyle, span,
             new BoxEdge(left, top, right, bottom));
@@ -1496,9 +1479,7 @@
     return null;
   }
 
-  /**
-   * Merge the two BorderExpression and return the result.
-   */
+  /// Merge the two BorderExpression and return the result.
   factory BorderExpression.merge(BorderExpression x, BorderExpression y) {
     return new BorderExpression._merge(x, y, y.span);
   }
@@ -1555,7 +1536,7 @@
 }
 
 class PaddingExpression extends BoxExpression {
-  /** Padding expression ripped apart. */
+  /// Padding expression ripped apart.
   PaddingExpression(SourceSpan span, {num top, num right, num bottom, num left})
       : super(DartStyleExpression.paddingStyle, span,
             new BoxEdge(left, top, right, bottom));
@@ -1573,9 +1554,7 @@
     return null;
   }
 
-  /**
-   * Merge the two PaddingExpression and return the result.
-   */
+  /// Merge the two PaddingExpression and return the result.
   factory PaddingExpression.merge(PaddingExpression x, PaddingExpression y) {
     return new PaddingExpression._merge(x, y, y.span);
   }
diff --git a/lib/src/tree_base.dart b/lib/src/tree_base.dart
index 3ead0bf..f662a7c 100644
--- a/lib/src/tree_base.dart
+++ b/lib/src/tree_base.dart
@@ -4,21 +4,19 @@
 
 part of csslib.visitor;
 
-/**
- * The base type for all nodes in a CSS abstract syntax tree.
- */
+/// The base type for all nodes in a CSS abstract syntax tree.
 abstract class TreeNode {
-  /** The source code this [TreeNode] represents. */
+  /// The source code this [TreeNode] represents.
   final SourceSpan span;
 
   TreeNode(this.span);
 
   TreeNode clone();
 
-  /** Classic double-dispatch visitor for implementing passes. */
+  /// Classic double-dispatch visitor for implementing passes.
   visit(VisitorBase visitor);
 
-  /** A multiline string showing the node and its children. */
+  /// A multiline string showing the node and its children.
   String toDebugString() {
     var to = new TreeOutput();
     var tp = new _TreePrinter(to, true);
@@ -27,12 +25,12 @@
   }
 }
 
-/** The base type for expressions. */
+/// The base type for expressions.
 abstract class Expression extends TreeNode {
   Expression(SourceSpan span) : super(span);
 }
 
-/** Simple class to provide a textual dump of trees for debugging. */
+/// Simple class to provide a textual dump of trees for debugging.
 class TreeOutput {
   int depth = 0;
   final StringBuffer buf = new StringBuffer();
diff --git a/lib/src/tree_printer.dart b/lib/src/tree_printer.dart
index 4f196c0..6aad40c 100644
--- a/lib/src/tree_printer.dart
+++ b/lib/src/tree_printer.dart
@@ -6,14 +6,14 @@
 
 // TODO(terry): Enable class for debug only; when conditional imports enabled.
 
-/** Helper function to dump the CSS AST. */
+/// Helper function to dump the CSS AST.
 String treeToDebugString(StyleSheet styleSheet, [bool useSpan = false]) {
   var to = new TreeOutput();
   new _TreePrinter(to, useSpan)..visitTree(styleSheet);
   return to.toString();
 }
 
-/** Tree dump for debug output of the CSS AST. */
+/// Tree dump for debug output of the CSS AST.
 class _TreePrinter extends Visitor {
   final TreeOutput output;
   final bool useSpan;
@@ -226,10 +226,8 @@
     output.depth--;
   }
 
-  /**
-   * Added optional newLine for handling @include at top-level vs/ inside of
-   * a declaration group.
-   */
+  /// Added optional newLine for handling @include at top-level vs/ inside of
+  /// a declaration group.
   void visitIncludeDirective(IncludeDirective node) {
     heading('IncludeDirective ${node.name}', node);
     var flattened = node.args.expand((e) => e).toList();
diff --git a/lib/src/validate.dart b/lib/src/validate.dart
index a98c665..72f14e0 100644
--- a/lib/src/validate.dart
+++ b/lib/src/validate.dart
@@ -7,7 +7,7 @@
 import 'package:csslib/visitor.dart';
 import 'package:source_span/source_span.dart';
 
-/** Can be thrown on any Css runtime problem includes source location. */
+/// Can be thrown on any Css runtime problem includes source location.
 class CssSelectorException extends SourceSpanException {
   CssSelectorException(String message, [SourceSpan span])
       : super(message, span);
diff --git a/lib/visitor.dart b/lib/visitor.dart
index 6e3af18..e2f1f04 100644
--- a/lib/visitor.dart
+++ b/lib/visitor.dart
@@ -116,9 +116,9 @@
   visitWidthExpression(WidthExpression node);
 }
 
-/** Base vistor class for the style sheet AST. */
+/// Base vistor class for the style sheet AST.
 class Visitor implements VisitorBase {
-  /** Helper function to walk a list of nodes. */
+  /// Helper function to walk a list of nodes.
   void _visitNodeList(List<TreeNode> list) {
     // Don't use iterable otherwise the list can't grow while using Visitor.
     // It certainly can't have items deleted before the index being iterated
diff --git a/test/compiler_test.dart b/test/compiler_test.dart
index 387137f..3e1852a 100644
--- a/test/compiler_test.dart
+++ b/test/compiler_test.dart
@@ -518,7 +518,7 @@
   expect("foobar", simpleSelector1.name);
 }
 
-/** Test List<int> as input to parser. */
+/// Test List<int> as input to parser.
 void testArrayOfChars() {
   var errors = <Message>[];
   var input = '<![CDATA[.foo { '
diff --git a/test/declaration_test.dart b/test/declaration_test.dart
index 55ab079..1cbceb9 100644
--- a/test/declaration_test.dart
+++ b/test/declaration_test.dart
@@ -82,10 +82,8 @@
   expect(errors.first.span.text, '%');
 }
 
-/**
- * Declarations with comments, references with single-quotes, double-quotes,
- * no quotes.  Hex values with # and letters, and functions (rgba, url, etc.)
- */
+/// Declarations with comments, references with single-quotes, double-quotes,
+/// no quotes.  Hex values with # and letters, and functions (rgba, url, etc.)
 void testDeclarations() {
   var errors = <Message>[];
   final String input = r'''
@@ -1072,16 +1070,14 @@
   expect(prettyPrint(stylesheet), input4);
 }
 
-/**
- *  Test IE specific declaration syntax:
- *    IE6 property name prefixed with _ (normal CSS property name can start
- *    with an underscore).
- *
- *    IE7 or below property add asterisk before the CSS property.
- *
- *    IE8 or below add \9 at end of declaration expression e.g.,
- *        background: red\9;
- */
+///  Test IE specific declaration syntax:
+///    IE6 property name prefixed with _ (normal CSS property name can start
+///    with an underscore).
+///
+///    IE7 or below property add asterisk before the CSS property.
+///
+///    IE8 or below add \9 at end of declaration expression e.g.,
+///        background: red\9;
 void testIEDeclaration() {
   var errors = <Message>[];
 
diff --git a/test/error_test.dart b/test/error_test.dart
index dbc3e7d..67af07e 100644
--- a/test/error_test.dart
+++ b/test/error_test.dart
@@ -9,9 +9,7 @@
 
 import 'testing.dart';
 
-/**
- * Test for unsupported font-weights values of bolder, lighter and inherit.
- */
+/// Test for unsupported font-weights values of bolder, lighter and inherit.
 void testUnsupportedFontWeights() {
   var errors = <Message>[];
 
@@ -71,10 +69,8 @@
 }''');
 }
 
-/**
- * Test for unsupported line-height values of units other than px, pt and
- * inherit.
- */
+/// Test for unsupported line-height values of units other than px, pt and
+/// inherit.
 void testUnsupportedLineHeights() {
   var errors = <Message>[];
 
@@ -132,7 +128,7 @@
 }''');
 }
 
-/** Test for bad selectors. */
+/// Test for bad selectors.
 void testBadSelectors() {
   var errors = <Message>[];
 
@@ -171,7 +167,7 @@
 }''');
 }
 
-/** Test for bad hex values. */
+/// Test for bad hex values.
 void testBadHexValues() {
   var errors = <Message>[];
 
diff --git a/test/mixin_test.dart b/test/mixin_test.dart
index 59071f9..e5d3ae7 100644
--- a/test/mixin_test.dart
+++ b/test/mixin_test.dart
@@ -69,7 +69,7 @@
 }''');
 }
 
-/** Tests top-level mixins that includes another mixin. */
+/// Tests top-level mixins that includes another mixin.
 void topLevelMixinMultiRulesets() {
   compileAndValidate(r'''
 @mixin a {
@@ -173,7 +173,7 @@
 }''');
 }
 
-/** Tests selector groups and other combinators. */
+/// Tests selector groups and other combinators.
 void topLevelMixinSelectors() {
   compileAndValidate(r'''
 @mixin a {
diff --git a/test/testing.dart b/test/testing.dart
index 6807576..33dbe7c 100644
--- a/test/testing.dart
+++ b/test/testing.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.
 
-/** Common definitions used for setting up the test environment. */
+/// Common definitions used for setting up the test environment.
 library testing;
 
 import 'package:csslib/parser.dart';
@@ -24,11 +24,9 @@
 const options = const PreprocessorOptions(
     useColors: false, warningsAsErrors: true, inputFile: 'memory');
 
-/**
- * Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
- * CSS will allow any property/value pairs regardless of validity; all of our
- * tests (by default) will ensure that the CSS is really valid.
- */
+/// Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
+/// CSS will allow any property/value pairs regardless of validity; all of our
+/// tests (by default) will ensure that the CSS is really valid.
 StyleSheet parseCss(String cssInput,
         {List<Message> errors, PreprocessorOptions opts}) =>
     parse(cssInput,
@@ -36,11 +34,9 @@
         options:
             opts == null ? simpleOptionsWithCheckedAndWarningsAsErrors : opts);
 
-/**
- * Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
- * CSS will allow any property/value pairs regardless of validity; all of our
- * tests (by default) will ensure that the CSS is really valid.
- */
+/// Spin-up CSS parser in checked mode to detect any problematic CSS.  Normally,
+/// CSS will allow any property/value pairs regardless of validity; all of our
+/// tests (by default) will ensure that the CSS is really valid.
 StyleSheet compileCss(String cssInput,
         {List<Message> errors,
         PreprocessorOptions opts,
@@ -57,30 +53,28 @@
         {List<Message> errors, PreprocessorOptions opts}) =>
     compileCss(input, errors: errors, polyfill: true, opts: opts);
 
-/** CSS emitter walks the style sheet tree and emits readable CSS. */
+/// CSS emitter walks the style sheet tree and emits readable CSS.
 final _emitCss = new CssPrinter();
 
-/** Simple Visitor does nothing but walk tree. */
+/// Simple Visitor does nothing but walk tree.
 final _cssVisitor = new Visitor();
 
-/** Pretty printer for CSS. */
+/// Pretty printer for CSS.
 String prettyPrint(StyleSheet ss) {
   // Walk the tree testing basic Vistor class.
   walkTree(ss);
   return (_emitCss..visitTree(ss, pretty: true)).toString();
 }
 
-/**
- * Helper function to emit compact (non-pretty printed) CSS for suite test
- * comparsions.  Spaces, new lines, etc. are reduced for easier comparsions of
- * expected suite test results.
- */
+/// Helper function to emit compact (non-pretty printed) CSS for suite test
+/// comparsions.  Spaces, new lines, etc. are reduced for easier comparsions of
+/// expected suite test results.
 String compactOuptut(StyleSheet ss) {
   walkTree(ss);
   return (_emitCss..visitTree(ss, pretty: false)).toString();
 }
 
-/** Walks the style sheet tree does nothing; insures the basic walker works. */
+/// Walks the style sheet tree does nothing; insures the basic walker works.
 void walkTree(StyleSheet ss) {
   _cssVisitor..visitTree(ss);
 }