[Sass] [SCSS] Modify the Sass documentation to take SCSS into account.

doc-src/SASS_REFERENCE.md

@@ -210,6 +210,13 @@ Available options are:
 : An option that's available for individual applications to set
   to make data available to {Sass::Script::Functions custom Sass functions}.
 
+{#syntax-option} `:syntax`
+: The syntax of the input file, `:sass` for the indented syntax
+  and `:scss` for the CSS syntax.
+  This is only useful when you're constructing {Sass::Engine} instances yourself;
+  it's automatically set properly when using {Sass::Plugin}.
+  Defaults to `:sass`.
+
 ## CSS Rules
 
 Rules in flat CSS have two elements:

lib/sass.rb

@@ -5,7 +5,7 @@ require 'haml/version'
 
 # The module that contains everything Sass-related:
 #
-# * {Sass::Engine} is the class used to render Sass within Ruby code.
+# * {Sass::Engine} is the class used to render Sass/SCSS within Ruby code.
 # * {Sass::Plugin} is interfaces with web frameworks (Rails and Merb in particular).
 # * {Sass::SyntaxError} is raised when Sass encounters an error.
 # * {Sass::CSS} handles conversion of CSS to Sass.

lib/sass/plugin.rb

@@ -3,7 +3,7 @@ require 'sass'
 require 'fileutils'
 
 module Sass
-  # This module handles the compilation of Sass files.
+  # This module handles the compilation of Sass/SCSS files.
   # It provides global options and checks whether CSS files
   # need to be updated.
   #
@@ -67,7 +67,7 @@ module Sass
 
     # Updates out-of-date stylesheets.
     #
-    # Checks each Sass file in {file:SASS_REFERENCE.md#template_location-option `:template_location`}
+    # Checks each Sass/SCSS file in {file:SASS_REFERENCE.md#template_location-option `:template_location`}
     # to see if it's been modified more recently than the corresponding CSS file
     # in {file:SASS_REFERENCE.md#css_location-option} `:css_location`}.
     # If it has, it updates the CSS file.

lib/sass/script/parser.rb

@@ -43,7 +43,7 @@ module Sass
       end
 
       # Parses a SassScript expression,
-      # ending it when it encounters one of the givne identifier tokens.
+      # ending it when it encounters one of the given identifier tokens.
       #
       # @param [#include?(String)] A set of strings that delimit the expression.
       # @return [Script::Node] The root node of the parse tree

lib/sass/tree/rule_node.rb

@@ -8,30 +8,20 @@ module Sass::Tree
     # The character used to include the parent selector
     PARENT = '&'
 
-    # The CSS selectors for this rule.
-    # Each string is a selector line, and the lines are meant to be separated by commas.
-    # For example,
+    # The (completely unparsed) CSS selector for this rule.
     #
-    #     foo, bar, baz,
-    #     bip, bop, bup
-    #
-    # would be
-    #
-    #     ["foo, bar, baz",
-    #      "bip, bop, bup"]
-    #
-    # @return [Array<String>]
+    # @return [String]
     attr_accessor :rule
 
     # The CSS selectors for this rule,
     # parsed for commas and parent-references.
     # It's only set once {Tree::Node#perform} has been called.
     #
-    # It's an array of arrays of arrays.
-    # The first level of arrays represents distinct lines in the Sass file;
-    # the second level represents comma-separated selectors;
-    # the third represents structure within those selectors,
+    # It's an array of arrays.
+    # The first level of arrays comma-separated selectors;
+    # the second represents structure within those selectors,
     # currently only parent-refs (represented by `:parent`).
+    # Newlines are represented as literal `\n` characters in the strings.
     # For example,
     #
     #     &.foo, bar, baz,
@@ -39,18 +29,18 @@ module Sass::Tree
     #
     # would be
     #
-    #     [[[:parent, ".foo"], ["bar"], ["baz"]],
-    #      [["bip"], [:parent, ".bop"], ["bup"]]]
+    #     [[:parent, ".foo"], ["bar"], ["baz"],
+    #      ["\nbip"], [:parent, ".bop"], ["bup"]]
     #
-    # @return [Array<Array<Array<String|Symbol>>>]
+    # @return [Array<Array<String|Symbol>>]
     attr_accessor :parsed_rules
 
     # The CSS selectors for this rule,
     # with all nesting and parent references resolved.
     # It's only set once {Tree::Node#cssize} has been called.
     #
-    # The first level of arrays represents distinct lines in the Sass file;
-    # the second level represents comma-separated selectors.
+    # Each element is a distinct selector, separated by commas.
+    # Newlines are represented as literal `\n` characters in the strings.
     # For example,
     #
     #     foo bar, baz,
@@ -58,10 +48,9 @@ module Sass::Tree
     #
     # would be
     #
-    #     [["foo bar", "baz"],
-    #      ["bang", "bip bop", "blip"]]
+    #     ["foo bar", "baz", "\nbang", "bip bop", "blip"]
     #
-    # @return [Array<Array<String>>]
+    # @return [Array<String>]
     attr_accessor :resolved_rules
 
     # How deep this rule is indented