Flip comments to modern doc-comment syntax
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);
}
