sass-embedded 1.0.8 → 1.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79aa99df78a2f126a39e870eff649dcad3dc0aa65eab3c1ad3c23f6f0075d4fc
-  data.tar.gz: aaa926824f1b40a5d0471b06d20617ee86e78d28896918dce5ee871b8702a925
+  metadata.gz: e66ada7e45e9d2645c9c11569f907001a4d8f9711df90f9cebe726e0a40d9539
+  data.tar.gz: aa2139021df463e31a2fa6f02d9515dd6b9553b57d73d38e831ad67ecb688275
 SHA512:
-  metadata.gz: 3ace91c8fb581c92ad264f9b9bd5ea0fe9dfa99dfbac3d773a6374cb2e9c1cf07e919a2d15cf75621eaa1cd3475b10b284737f14e803778f285a20447b37c070
-  data.tar.gz: 74f456b0b6a50886e508b2dda49a5e91d714d170f3a221b3e174c6ce186fed9fd382ce271edb55a85e02d223413a78bca3a324fa9f974b9781bcb9bb3750a9a3
+  metadata.gz: bc77ad8ef5cbd139360443308899212ce95fd4b3be3be31fbca1f331f7cc73e6bd5ad0f6f2bc853d486ca0a90bc1e3fdf043adbcb534060f17c2209a7eac9499
+  data.tar.gz: 61918d88ebfa21159851b0294d1366b2ff403c3168592dc70554c68810a777552ecb773849e790fd9f8bd1be1f2e4839732700b02a5faf7b4db448776c34b120

data/README.md

@@ -15,11 +15,24 @@ gem install sass-embedded
 
 ## Usage
 
+The Ruby API provides two entrypoints for compiling Sass to CSS.
+
+- `Sass.compile` takes a path to a Sass file and return the result of compiling that file to CSS.
+
+``` ruby
+require 'sass'
+
+result = Sass.compile('style.scss')
+puts result.css
+```
+
+- `Sass.compile_string` takes a string that represents the contents of a Sass file and return the result of compiling that file to CSS.
+
 ``` ruby
 require 'sass'
 
-Sass.compile('style.scss')
-Sass.compile_string('h1 { font-size: 40px; }')
+result = Sass.compile_string('h1 { font-size: 40px; }')
+puts result.css
 ```
 
 ---

data/lib/sass/compile_error.rb

@@ -3,18 +3,23 @@
 module Sass
   # An exception thrown because a Sass compilation failed.
   class CompileError < StandardError
-    attr_accessor :sass_stack, :span
+    # @return [String, nil]
+    attr_accessor :sass_stack
+
+    # @return [Logger::SourceSpan, nil]
+    attr_accessor :span
 
     def initialize(message, full_message, sass_stack, span)
       super(message)
-      @full_message = full_message
-      @sass_stack = sass_stack
+      @full_message = full_message == '' ? nil : full_message.dup
+      @sass_stack = sass_stack == '' ? nil : sass_stack
       @span = span
     end
 
-    def full_message(*)
+    # @return [String]
+    def full_message(*args, **kwargs)
       if @full_message.nil?
-        super
+        super(*args, **kwargs)
       else
         @full_message
       end

data/lib/sass/compile_result.rb

@@ -2,8 +2,17 @@
 
 module Sass
   # The result of compiling Sass to CSS. Returned by {Sass.compile} and {Sass.compile_string}.
+  #
+  # @see https://sass-lang.com/documentation/js-api/interfaces/CompileResult
   class CompileResult
-    attr_reader :css, :source_map, :loaded_urls
+    # @return [String]
+    attr_reader :css
+
+    # @return [String, nil]
+    attr_reader :source_map
+
+    # @return [Array<String>]
+    attr_reader :loaded_urls
 
     def initialize(css, source_map, loaded_urls)
       @css = css

data/lib/sass/embedded/host.rb

@@ -36,6 +36,8 @@ module Sass
                           quiet_deps:,
                           verbose:)
         await do
+          alert_color = $stderr.tty? if alert_color.nil?
+
           @function_registry = FunctionRegistry.new(functions, alert_color: alert_color)
           @importer_registry = ImporterRegistry.new(importers, load_paths, alert_color: alert_color)
           @logger_registry = LoggerRegistry.new(logger)

data/lib/sass/embedded/version.rb

@@ -2,6 +2,6 @@
 
 module Sass
   class Embedded
-    VERSION = '1.0.8'
+    VERSION = '1.0.9'
   end
 end

data/lib/sass/embedded.rb

@@ -14,10 +14,31 @@ module Sass
       @channel = Channel.new
     end
 
-    # The {Embedded#compile} method.
-    #
+    # Compiles the Sass file at +path+ to CSS.
+    # @param path [String]
+    # @param load_paths [Array<String>] Paths in which to look for stylesheets loaded by rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param source_map [Boolean] Whether or not Sass should generate a source map.
+    # @param source_map_include_sources [Boolean] Whether Sass should include the sources in the generated source map.
+    # @param style [String, Symbol] The OutputStyle of the compiled CSS.
+    # @param functions [Hash<String, Proc>] Additional built-in Sass functions that are available in all stylesheets.
+    # @param importers [Array<Object>] Custom importers that control how Sass resolves loads from rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param alert_ascii [Boolean] If this is +true+, the compiler will exclusively use ASCII characters in its error
+    #   and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.
+    # @param alert_color [Boolean] If this is +true+, the compiler will use ANSI color escape codes in its error and
+    #   warning messages. If it's +false+, it won't use these. If it's +nil+, the compiler will determine whether or
+    #   not to use colors depending on whether the user is using an interactive terminal.
+    # @param logger [Object] An object to use to handle warnings and/or debug messages from Sass.
+    # @param quiet_deps [Boolean] If this option is set to +true+, Sass won’t print warnings that are caused by
+    #   dependencies. A “dependency” is defined as any file that’s loaded through +load_paths+ or +importer+.
+    #   Stylesheets that are imported relative to the entrypoint are not considered dependencies.
+    # @param verbose [Boolean] By default, Dart Sass will print only five instances of the same deprecation warning per
+    #   compilation to avoid deluging users in console noise. If you set verbose to +true+, it will instead print every
+    #   deprecation warning it encounters.
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see https://sass-lang.com/documentation/js-api/modules#compile
     def compile(path,
                 load_paths: [],
 
@@ -29,7 +50,7 @@ module Sass
                 importers: [],
 
                 alert_ascii: false,
-                alert_color: $stderr.tty?,
+                alert_color: nil,
                 logger: nil,
                 quiet_deps: false,
                 verbose: false)
@@ -58,10 +79,35 @@ module Sass
       )
     end
 
-    # The {Embedded#compile_string} method.
-    #
+    # Compiles a stylesheet whose contents is +source+ to CSS.
+    # @param source [String]
+    # @param importer [Object] The importer to use to handle loads that are relative to the entrypoint stylesheet.
+    # @param load_paths [Array<String>] Paths in which to look for stylesheets loaded by rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param syntax [String, Symbol] The Syntax to use to parse the entrypoint stylesheet.
+    # @param url [String] The canonical URL of the entrypoint stylesheet. If this is passed along with +importer+, it's
+    #   used to resolve relative loads in the entrypoint stylesheet.
+    # @param source_map [Boolean] Whether or not Sass should generate a source map.
+    # @param source_map_include_sources [Boolean] Whether Sass should include the sources in the generated source map.
+    # @param style [String, Symbol] The OutputStyle of the compiled CSS.
+    # @param functions [Hash<String, Proc>] Additional built-in Sass functions that are available in all stylesheets.
+    # @param importers [Array<Object>] Custom importers that control how Sass resolves loads from rules like
+    #   {@use}[https://sass-lang.com/documentation/at-rules/use] and {@import}[https://sass-lang.com/documentation/at-rules/import].
+    # @param alert_ascii [Boolean] If this is +true+, the compiler will exclusively use ASCII characters in its error
+    #   and warning messages. Otherwise, it may use non-ASCII Unicode characters as well.
+    # @param alert_color [Boolean] If this is +true+, the compiler will use ANSI color escape codes in its error and
+    #   warning messages. If it's +false+, it won't use these. If it's +nil+, the compiler will determine whether or
+    #   not to use colors depending on whether the user is using an interactive terminal.
+    # @param logger [Object] An object to use to handle warnings and/or debug messages from Sass.
+    # @param quiet_deps [Boolean] If this option is set to +true+, Sass won’t print warnings that are caused by
+    #   dependencies. A “dependency” is defined as any file that’s loaded through +load_paths+ or +importer+.
+    #   Stylesheets that are imported relative to the entrypoint are not considered dependencies.
+    # @param verbose [Boolean] By default, Dart Sass will print only five instances of the same deprecation warning per
+    #   compilation to avoid deluging users in console noise. If you set verbose to +true+, it will instead print every
+    #   deprecation warning it encounters.
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see https://sass-lang.com/documentation/js-api/modules#compileString
     def compile_string(source,
                        importer: nil,
                        load_paths: [],
@@ -76,7 +122,7 @@ module Sass
                        importers: [],
 
                        alert_ascii: false,
-                       alert_color: $stderr.tty?,
+                       alert_color: nil,
                        logger: nil,
                        quiet_deps: false,
                        verbose: false)
@@ -104,7 +150,8 @@ module Sass
       )
     end
 
-    # The {Embedded#info} method.
+    # @return [String] Information about the Sass implementation.
+    # @see https://sass-lang.com/documentation/js-api/modules#info
     def info
       @info ||= "sass-embedded\t#{Host.new(@channel).version_request.implementation_version}"
     end

data/lib/sass/logger/source_location.rb

@@ -5,7 +5,10 @@ module Sass
     # A specific location within a source file.
     #
     # This is always associated with a {SourceSpan} which indicates which file it refers to.
+    #
+    # @see https://sass-lang.com/documentation/js-api/interfaces/SourceLocation
     class SourceLocation
+      # @return [Integer]
       attr_reader :offset, :line, :column
 
       def initialize(offset, line, column)

data/lib/sass/logger/source_span.rb

@@ -3,8 +3,17 @@
 module Sass
   module Logger
     # A span of text within a source file.
+    #
+    # @see https://sass-lang.com/documentation/js-api/interfaces/SourceSpan
     class SourceSpan
-      attr_reader :start, :end, :text, :url, :context
+      # @return [SourceLocation]
+      attr_reader :start, :end
+
+      # @return [String]
+      attr_reader :text
+
+      # @return [String, nil]
+      attr_reader :url, :context
 
       def initialize(start, end_, text, url, context)
         @start = start

data/lib/sass/logger.rb

@@ -2,6 +2,8 @@
 
 module Sass
   # A namespace for built-in Loggers.
+  #
+  # @see https://sass-lang.com/documentation/js-api/modules/Logger
   module Logger
     module_function
 

data/lib/sass/value/argument_list.rb

@@ -6,7 +6,12 @@ module Sass
     #
     # An argument list comes from a rest argument. It's distinct from a normal {List} in that it may contain a keyword
     # map as well as the positional arguments.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassArgumentList
     class ArgumentList < Value::List
+      # @param contents [Array<Value>]
+      # @param keywords [Hash<::String, Value>]
+      # @param separator [::String]
       def initialize(contents = [], keywords = {}, separator = ',')
         super(contents, separator: separator)
 
@@ -15,6 +20,7 @@ module Sass
         @keywords = keywords.transform_keys(&:to_s).freeze
       end
 
+      # @return [Hash<::String, Value>]
       def keywords
         @keywords_accessed = true
         @keywords

data/lib/sass/value/boolean.rb

@@ -3,31 +3,39 @@
 module Sass
   module Value
     # Sass's boolean type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassBoolean
     class Boolean
       include Value
 
+      # @param value [::Boolean]
       def initialize(value)
         @value = value
       end
 
+      # @return [::Boolean]
       attr_reader :value
 
-      alias to_bool value
-
-      def assert_boolean(_name = nil)
-        self
+      # @return [Boolean]
+      def !
+        value ? Boolean::FALSE : Boolean::TRUE
       end
 
+      # @return [::Boolean]
       def ==(other)
         other.is_a?(Sass::Value::Boolean) && other.value == value
       end
 
+      # @return [Integer]
       def hash
         @hash ||= value.hash
       end
 
-      def !
-        value ? Boolean::FALSE : Boolean::TRUE
+      alias to_bool value
+
+      # @return [Boolean]
+      def assert_boolean(_name = nil)
+        self
       end
 
       # Sass's true value.

data/lib/sass/value/color.rb

@@ -5,9 +5,20 @@ module Sass
     # Sass's color type.
     #
     # No matter what representation was originally used to create this color, all of its channels are accessible.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassColor
     class Color
       include Value
 
+      # @param red [Numeric]
+      # @param green [Numeric]
+      # @param blue [Numeric]
+      # @param hue [Numeric]
+      # @param saturation [Numeric]
+      # @param lightness [Numeric]
+      # @param whiteness [Numeric]
+      # @param blackness [Numeric]
+      # @param alpha [Numeric]
       def initialize(red: nil,
                      green: nil,
                      blue: nil,
@@ -37,88 +48,104 @@ module Sass
         end
       end
 
-      def change(red: nil,
-                 green: nil,
-                 blue: nil,
-                 hue: nil,
-                 saturation: nil,
-                 lightness: nil,
-                 whiteness: nil,
-                 blackness: nil,
-                 alpha: nil)
-        if whiteness || blackness
-          Sass::Value::Color.new(hue: hue || self.hue,
-                                 whiteness: whiteness || self.whiteness,
-                                 blackness: blackness || self.blackness,
-                                 alpha: alpha || self.alpha)
-        elsif hue || saturation || lightness
-          Sass::Value::Color.new(hue: hue || self.hue,
-                                 saturation: saturation || self.saturation,
-                                 lightness: lightness || self.lightness,
-                                 alpha: alpha || self.alpha)
-        elsif red || green || blue
-          Sass::Value::Color.new(red: red ? FuzzyMath.round(red) : self.red,
-                                 green: green ? FuzzyMath.round(green) : self.green,
-                                 blue: blue ? FuzzyMath.round(blue) : self.blue,
-                                 alpha: alpha || self.alpha)
-        else
-          dup.instance_eval do
-            @alpha = FuzzyMath.assert_between(alpha, 0, 1, 'alpha')
-            self
-          end
-        end
-      end
-
+      # @return [Integer]
       def red
         hsl_to_rgb unless defined? @red
 
         @red
       end
 
+      # @return [Integer]
       def green
         hsl_to_rgb unless defined? @green
 
         @green
       end
 
+      # @return [Integer]
       def blue
         hsl_to_rgb unless defined? @blue
 
         @blue
       end
 
+      # @return [Numeric]
       def hue
         rgb_to_hsl unless defined? @hue
 
         @hue
       end
 
+      # @return [Numeric]
       def saturation
         rgb_to_hsl unless defined? @saturation
 
         @saturation
       end
 
+      # @return [Numeric]
       def lightness
         rgb_to_hsl unless defined? @lightness
 
         @lightness
       end
 
+      # @return [Numeric]
       def whiteness
         @whiteness ||= Rational([red, green, blue].min, 255) * 100
       end
 
+      # @return [Numeric]
       def blackness
         @blackness ||= 100 - (Rational([red, green, blue].max, 255) * 100)
       end
 
+      # @return [Numeric]
       attr_reader :alpha
 
-      def assert_color(_name = nil)
-        self
+      # @param red [Numeric]
+      # @param green [Numeric]
+      # @param blue [Numeric]
+      # @param hue [Numeric]
+      # @param saturation [Numeric]
+      # @param lightness [Numeric]
+      # @param whiteness [Numeric]
+      # @param blackness [Numeric]
+      # @param alpha [Numeric]
+      # @return [Color]
+      def change(red: nil,
+                 green: nil,
+                 blue: nil,
+                 hue: nil,
+                 saturation: nil,
+                 lightness: nil,
+                 whiteness: nil,
+                 blackness: nil,
+                 alpha: nil)
+        if whiteness || blackness
+          Sass::Value::Color.new(hue: hue || self.hue,
+                                 whiteness: whiteness || self.whiteness,
+                                 blackness: blackness || self.blackness,
+                                 alpha: alpha || self.alpha)
+        elsif hue || saturation || lightness
+          Sass::Value::Color.new(hue: hue || self.hue,
+                                 saturation: saturation || self.saturation,
+                                 lightness: lightness || self.lightness,
+                                 alpha: alpha || self.alpha)
+        elsif red || green || blue
+          Sass::Value::Color.new(red: red ? FuzzyMath.round(red) : self.red,
+                                 green: green ? FuzzyMath.round(green) : self.green,
+                                 blue: blue ? FuzzyMath.round(blue) : self.blue,
+                                 alpha: alpha || self.alpha)
+        else
+          dup.instance_eval do
+            @alpha = FuzzyMath.assert_between(alpha, 0, 1, 'alpha')
+            self
+          end
+        end
       end
 
+      # @return [::Boolean]
       def ==(other)
         other.is_a?(Sass::Value::Color) &&
           other.red == red &&
@@ -127,10 +154,16 @@ module Sass
           other.alpha == alpha
       end
 
+      # @return [Integer]
       def hash
         @hash ||= red.hash ^ green.hash ^ blue.hash ^ alpha.hash
       end
 
+      # @return [Color]
+      def assert_color(_name = nil)
+        self
+      end
+
       private
 
       def rgb_to_hsl

data/lib/sass/value/function.rb

@@ -3,9 +3,13 @@
 module Sass
   module Value
     # Sass's function type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassFunction
     class Function
       include Value
 
+      # @param id_or_signature [Numeric, ::String]
+      # @param callback [Proc]
       def initialize(id_or_signature, callback = nil)
         if id_or_signature.is_a? Numeric
           @id = id_or_signature
@@ -15,12 +19,16 @@ module Sass
         end
       end
 
-      attr_reader :id, :signature, :callback
+      # @return [Integer, nil]
+      attr_reader :id
 
-      def assert_function(_name = nil)
-        self
-      end
+      # @return [::String, nil]
+      attr_reader :signature
+
+      # @return [Proc, nil]
+      attr_reader :callback
 
+      # @return [::Boolean]
       def ==(other)
         if id.nil?
           other.equal? self
@@ -29,9 +37,15 @@ module Sass
         end
       end
 
+      # @return [Integer]
       def hash
         id.nil? ? signature.hash : id.hash
       end
+
+      # @return [Function]
+      def assert_function(_name = nil)
+        self
+      end
     end
   end
 end

data/lib/sass/value/list.rb

@@ -3,9 +3,14 @@
 module Sass
   module Value
     # Sass's list type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassList
     class List
       include Value
 
+      # @param contents [Array<Value>]
+      # @param separator [::String]
+      # @param bracketed [::Boolean]
       def initialize(contents = [], separator: ',', bracketed: false)
         if separator.nil? && contents.length > 1
           raise error 'A list with more than one element must have an explicit separator'
@@ -16,22 +21,28 @@ module Sass
         @bracketed = bracketed.freeze
       end
 
-      attr_reader :contents, :separator
+      # @return [Array<Value>]
+      attr_reader :contents
 
-      alias to_a contents
+      # @return [::String, nil]
+      attr_reader :separator
 
+      # @return [::Boolean]
       def bracketed?
         @bracketed
       end
 
-      def assert_map(name = nil)
-        to_a.empty? ? Sass::Value::Map.new({}) : super.assert_map(name)
-      end
-
-      def to_map
-        to_a.empty? ? Sass::Value::Map.new({}) : nil
+      # @return [::Boolean]
+      def ==(other)
+        (other.is_a?(Sass::Value::List) &&
+         other.contents == contents &&
+         other.separator == separator &&
+         other.bracketed? == bracketed?) ||
+          (to_a.empty? && other.is_a?(Sass::Value::Map) && other.to_a.empty?)
       end
 
+      # @param index [Numeric]
+      # @return [Value]
       def at(index)
         index = index.floor
         index = to_a.length + index if index.negative?
@@ -40,18 +51,24 @@ module Sass
         to_a[index]
       end
 
-      def ==(other)
-        (other.is_a?(Sass::Value::List) &&
-         other.contents == contents &&
-         other.separator == separator &&
-         other.bracketed? == bracketed?) ||
-          (to_a.empty? && other.is_a?(Sass::Value::Map) && other.to_a.empty?)
-      end
-
+      # @return [Integer]
       def hash
         @hash ||= contents.hash
       end
 
+      alias to_a contents
+
+      # @return [Map, nil]
+      def to_map
+        to_a.empty? ? Sass::Value::Map.new({}) : nil
+      end
+
+      # @return [Map]
+      # @raise [ScriptError]
+      def assert_map(name = nil)
+        to_a.empty? ? Sass::Value::Map.new({}) : super.assert_map(name)
+      end
+
       private
 
       def to_a_length

data/lib/sass/value/map.rb

@@ -3,31 +3,32 @@
 module Sass
   module Value
     # Sass's map type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassMap
     class Map
       include Value
 
+      # @param contents [Hash<Value, Value>]
       def initialize(contents = {})
         @contents = contents.freeze
       end
 
+      # @return [Hash<Value, Value>]
       attr_reader :contents
 
+      # @return [::String, nil]
       def separator
         contents.empty? ? nil : ','
       end
 
-      def assert_map(_name = nil)
-        self
-      end
-
-      def to_map
-        self
-      end
-
-      def to_a
-        contents.to_a.map { |entry| Sass::Value::List.new(entry, separator: ' ') }
+      # @return [::Boolean]
+      def ==(other)
+        (other.is_a?(Sass::Value::Map) && other.contents == contents) ||
+          (contents.empty? && other.is_a?(Sass::Value::List) && other.to_a.empty?)
       end
 
+      # @param index [Numeric, Value]
+      # @return [List<(Value, Value)>, Value]
       def at(index)
         if index.is_a? Numeric
           index = index.floor
@@ -40,15 +41,26 @@ module Sass
         end
       end
 
-      def ==(other)
-        (other.is_a?(Sass::Value::Map) && other.contents == contents) ||
-          (contents.empty? && other.is_a?(Sass::Value::List) && other.to_a.empty?)
-      end
-
+      # @return [Integer]
       def hash
         @hash ||= contents.hash
       end
 
+      # @return [Array<List<(Value, Value)>>]
+      def to_a
+        contents.to_a.map { |entry| Sass::Value::List.new(entry, separator: ' ') }
+      end
+
+      # @return [Map]
+      def to_map
+        self
+      end
+
+      # @return [Map]
+      def assert_map(_name = nil)
+        self
+      end
+
       private
 
       def to_a_length

data/lib/sass/value/null.rb

@@ -3,6 +3,8 @@
 module Sass
   module Value
     # Sass's null type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/modules#sassNull
     class Null
       include Value
 
@@ -10,26 +12,31 @@ module Sass
         @value = nil
       end
 
+      # @return [nil]
       attr_reader :value
 
-      alias to_nil value
-
-      def to_bool
-        false
+      # @return [Boolean]
+      def !
+        Boolean::TRUE
       end
 
+      # @return [::Boolean]
       def ==(other)
         other.is_a?(Sass::Value::Null)
       end
 
+      # @return [Integer]
       def hash
         @hash ||= value.hash
       end
 
-      def !
-        Boolean::TRUE
+      # @return [::Boolean]
+      def to_bool
+        false
       end
 
+      alias to_nil value
+
       # Sass's null value.
       NULL = Null.new
 

data/lib/sass/value/number.rb

@@ -3,9 +3,14 @@
 module Sass
   module Value
     # Sass's number type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassNumber
     class Number
       include Value
 
+      # @param value [Numeric]
+      # @param numerator_units [Array<::String>, ::String]
+      # @param denominator_units [Array<::String>, ::String]
       def initialize(value, numerator_units = [], denominator_units = [])
         numerator_units = [numerator_units] if numerator_units.is_a?(::String)
         denominator_units = [denominator_units] if denominator_units.is_a?(::String)
@@ -40,65 +45,141 @@ module Sass
         @denominator_units = denominator_units.freeze
       end
 
-      attr_reader :value, :numerator_units, :denominator_units
+      # @return [Numeric]
+      attr_reader :value
 
+      # @return [Array<::String>]
+      attr_reader :numerator_units, :denominator_units
+
+      # @return [::Boolean]
+      def ==(other)
+        return false unless other.is_a? Sass::Value::Number
+
+        return false if numerator_units.length != other.numerator_units.length ||
+                        denominator_units.length != other.denominator_units.length
+
+        return FuzzyMath.equals(value, other.value) if unitless?
+
+        if Unit.canonicalize_units(numerator_units) != Unit.canonicalize_units(other.numerator_units) &&
+           Unit.canonicalize_units(denominator_units) != Unit.canonicalize_units(other.denominator_units)
+          return false
+        end
+
+        FuzzyMath.equals(
+          (value *
+          Unit.canonical_multiplier(numerator_units) /
+          Unit.canonical_multiplier(denominator_units)),
+          (other.value *
+          Unit.canonical_multiplier(other.numerator_units) /
+          Unit.canonical_multiplier(other.denominator_units))
+        )
+      end
+
+      # @return [Integer]
+      def hash
+        @hash ||= if unitless?
+                    FuzzyMath.hash(value)
+                  elsif single_unit?
+                    FuzzyMath.hash(
+                      value * Unit.canonical_multiplier_for_unit(numerator_units.first)
+                    )
+                  else
+                    FuzzyMath.hash(
+                      value * Unit.canonical_multiplier(numerator_units) / Unit.canonical_multiplier(denominator_units)
+                    )
+                  end
+      end
+
+      # @return [::Boolean]
       def unitless?
         numerator_units.empty? && denominator_units.empty?
       end
 
+      # @return [Number]
+      # @raise [ScriptError]
       def assert_unitless(name = nil)
         raise error "Expected #{self} to have no units", name unless unitless?
+
+        self
       end
 
+      # @return [::Boolean]
       def units?
         !unitless?
       end
 
+      # @param unit [::String]
+      # @return [::Boolean]
       def unit?(unit)
         single_unit? && numerator_units.first == unit
       end
 
+      # @param unit [::String]
+      # @return [Number]
+      # @raise [ScriptError]
       def assert_unit(unit, name = nil)
         raise error "Expected #{self} to have no unit \"#{unit}\"", name unless unit?(unit)
+
+        self
       end
 
+      # @return [::Boolean]
       def integer?
         FuzzyMath.integer?(value)
       end
 
+      # @return [Integer]
+      # @raise [ScriptError]
       def assert_integer(name = nil)
         raise error "#{self} is not an integer", name unless integer?
 
         to_i
       end
 
+      # @return [Integer]
       def to_i
         FuzzyMath.to_i(value)
       end
 
+      # @param min [Numeric]
+      # @param max [Numeric]
+      # @return [Numeric]
+      # @raise [ScriptError]
       def assert_between(min, max, name = nil)
         FuzzyMath.assert_between(value, min, max, name)
       end
 
+      # @param unit [::String]
+      # @return [::Boolean]
       def compatible_with_unit?(unit)
         single_unit? && !Unit.conversion_factor(numerator_units.first, unit).nil?
       end
 
+      # @param new_numerator_units [Array<::String>]
+      # @param new_denominator_units [Array<::String>]
+      # @return [Number]
       def convert(new_numerator_units, new_denominator_units, name = nil)
         Number.new(convert_value(new_numerator_units, new_denominator_units, name), new_numerator_units,
                    new_denominator_units)
       end
 
+      # @param new_numerator_units [Array<::String>]
+      # @param new_denominator_units [Array<::String>]
+      # @return [Numeric]
       def convert_value(new_numerator_units, new_denominator_units, name = nil)
         coerce_or_convert_value(new_numerator_units, new_denominator_units,
                                 coerce_unitless: false,
                                 name: name)
       end
 
+      # @param other [Number]
+      # @return [Number]
       def convert_to_match(other, name = nil, other_name = nil)
         Number.new(convert_value_to_match(other, name, other_name), other.numerator_units, other.denominator_units)
       end
 
+      # @param other [Number]
+      # @return [Numeric]
       def convert_value_to_match(other, name = nil, other_name = nil)
         coerce_or_convert_value(other.numerator_units, other.denominator_units,
                                 coerce_unitless: false,
@@ -107,25 +188,37 @@ module Sass
                                 other_name: other_name)
       end
 
+      # @param new_numerator_units [Array<::String>]
+      # @param new_denominator_units [Array<::String>]
+      # @return [Number]
       def coerce(new_numerator_units, new_denominator_units, name = nil)
         Number.new(coerce_value(new_numerator_units, new_denominator_units, name), new_numerator_units,
                    new_denominator_units)
       end
 
+      # @param new_numerator_units [Array<::String>]
+      # @param new_denominator_units [Array<::String>]
+      # @return [Numeric]
       def coerce_value(new_numerator_units, new_denominator_units, name = nil)
         coerce_or_convert_value(new_numerator_units, new_denominator_units,
                                 coerce_unitless: true,
                                 name: name)
       end
 
+      # @param unit [::String]
+      # @return [Numeric]
       def coerce_value_to_unit(unit, name = nil)
         coerce_value([unit], [], name)
       end
 
+      # @param other [Number]
+      # @return [Number]
       def coerce_to_match(other, name = nil, other_name = nil)
         Number.new(coerce_value_to_match(other, name, other_name), other.numerator_units, other.denominator_units)
       end
 
+      # @param other [Number]
+      # @return [Numeric]
       def coerce_value_to_match(other, name = nil, other_name = nil)
         coerce_or_convert_value(other.numerator_units, other.denominator_units,
                                 coerce_unitless: true,
@@ -134,47 +227,11 @@ module Sass
                                 other_name: other_name)
       end
 
+      # @return [Number]
       def assert_number(_name = nil)
         self
       end
 
-      def ==(other)
-        return false unless other.is_a? Sass::Value::Number
-
-        return false if numerator_units.length != other.numerator_units.length ||
-                        denominator_units.length != other.denominator_units.length
-
-        return FuzzyMath.equals(value, other.value) if unitless?
-
-        if Unit.canonicalize_units(numerator_units) != Unit.canonicalize_units(other.numerator_units) &&
-           Unit.canonicalize_units(denominator_units) != Unit.canonicalize_units(other.denominator_units)
-          return false
-        end
-
-        FuzzyMath.equals(
-          (value *
-          Unit.canonical_multiplier(numerator_units) /
-          Unit.canonical_multiplier(denominator_units)),
-          (other.value *
-          Unit.canonical_multiplier(other.numerator_units) /
-          Unit.canonical_multiplier(other.denominator_units))
-        )
-      end
-
-      def hash
-        @hash ||= if unitless?
-                    FuzzyMath.hash(value)
-                  elsif single_unit?
-                    FuzzyMath.hash(
-                      value * Unit.canonical_multiplier_for_unit(numerator_units.first)
-                    )
-                  else
-                    FuzzyMath.hash(
-                      value * Unit.canonical_multiplier(numerator_units) / Unit.canonical_multiplier(denominator_units)
-                    )
-                  end
-      end
-
       protected
 
       def single_unit?

data/lib/sass/value/string.rb

@@ -3,42 +3,53 @@
 module Sass
   module Value
     # Sass's string type.
+    #
+    # @see https://sass-lang.com/documentation/js-api/classes/SassString
     class String
       include Value
 
+      # @param text [::String]
+      # @param quoted: [::Boolean]
       def initialize(text = '', quoted: true)
         @text = text.freeze
         @quoted = quoted
       end
 
+      # @return [::String]
       attr_reader :text
 
+      # @return [::Boolean]
       def quoted?
         @quoted
       end
 
-      def sass_index_to_string_index(sass_index, name = nil)
-        index = sass_index.assert_number(name).assert_integer(name)
-        raise error('String index may not be 0', name) if index.zero?
-
-        if index.abs > text.length
-          raise error("Invalid index #{sass_index} for a string with #{text.length} characters", name)
-        end
-
-        index.negative? ? text.length + index : index - 1
-      end
-
+      # @return [::Boolean]
       def ==(other)
         other.is_a?(Sass::Value::String) && other.text == text
       end
 
+      # @return [Integer]
       def hash
         @hash ||= text.hash
       end
 
+      # @return [String]
       def assert_string(_name = nil)
         self
       end
+
+      # @param sass_index [Number]
+      # @return [Integer]
+      def sass_index_to_string_index(sass_index, name = nil)
+        index = sass_index.assert_number(name).assert_integer(name)
+        raise error('String index may not be 0', name) if index.zero?
+
+        if index.abs > text.length
+          raise error("Invalid index #{sass_index} for a string with #{text.length} characters", name)
+        end
+
+        index.negative? ? text.length + index : index - 1
+      end
     end
   end
 end

data/lib/sass/value.rb

@@ -2,80 +2,108 @@
 
 module Sass
   # The abstract base class of Sass's value types.
+  #
+  # @see https://sass-lang.com/documentation/js-api/classes/Value
   module Value
-    def to_a
-      [self]
+    # @return [::String, nil]
+    def separator
+      nil
     end
 
-    def to_bool
-      true
+    # @return [::Boolean]
+    def bracketed?
+      false
     end
 
-    def to_map
-      nil
+    # @return [::Boolean]
+    def eql?(other)
+      self == other
     end
 
-    def to_nil
-      self
+    # @param index [Numeric]
+    # @return [Value]
+    def [](index)
+      at(index)
     end
 
-    def separator
-      nil
+    # @param index [Numeric]
+    # @return [Value]
+    def at(index)
+      index < 1 && index >= -1 ? self : nil
     end
 
-    def bracketed?
-      false
+    # @return [Array<Value>]
+    def to_a
+      [self]
     end
 
-    def sass_index_to_array_index(sass_index, name = nil)
-      index = sass_index.assert_number(name).assert_integer(name)
-      raise error('List index may not be 0', name) if index.zero?
-
-      if index.abs > to_a_length
-        raise error("Invalid index #{sass_index} for a list with #{to_a_length} elements", name)
-      end
-
-      index.negative? ? to_a_length + index : index - 1
+    # @return [::Boolean]
+    def to_bool
+      true
     end
 
-    def at(index)
-      index < 1 && index >= -1 ? self : nil
+    # @return [Map, nil]
+    def to_map
+      nil
     end
 
-    def [](index)
-      at(index)
+    # @return [Value, nil]
+    def to_nil
+      self
     end
 
+    # @return [Boolean]
+    # @raise [ScriptError]
     def assert_boolean(name = nil)
       raise error("#{self} is not a boolean", name)
     end
 
+    # @raise [ScriptError]
     def assert_calculation(name = nil)
       raise error("#{self} is not a calculation", name)
     end
 
+    # @return [Color]
+    # @raise [ScriptError]
     def assert_color(name = nil)
       raise error("#{self} is not a color", name)
     end
 
+    # @return [Function]
+    # @raise [ScriptError]
     def assert_function(name = nil)
       raise error("#{self} is not a function", name)
     end
 
+    # @return [Map]
+    # @raise [ScriptError]
     def assert_map(name = nil)
       raise error("#{self} is not a map", name)
     end
 
+    # @return [Number]
+    # @raise [ScriptError]
     def assert_number(name = nil)
       raise error("#{self} is not a number", name)
     end
 
+    # @return [String]
+    # @raise [ScriptError]
     def assert_string(name = nil)
       raise error("#{self} is not a string", name)
     end
 
-    def eql?(other)
-      self == other
+    # @param sass_index [Number]
+    # @return [Integer]
+    def sass_index_to_array_index(sass_index, name = nil)
+      index = sass_index.assert_number(name).assert_integer(name)
+      raise error('List index may not be 0', name) if index.zero?
+
+      if index.abs > to_a_length
+        raise error("Invalid index #{sass_index} for a list with #{to_a_length} elements", name)
+      end
+
+      index.negative? ? to_a_length + index : index - 1
     end
 
     private

data/lib/sass.rb

@@ -37,39 +37,30 @@ require_relative 'sass/value/string'
 # The Sass module.
 #
 # This communicates with Embedded Dart Sass using the Embedded Sass protocol.
+#
+# @example
+#   Sass.compile('style.scss')
+#
+# @example
+#   Sass.compile_string('h1 { font-size: 40px; }')
 module Sass
   class << self
-    # The global {.compile} method.
-    #
-    # This instantiates a global {Embedded} instance and calls {Embedded#compile}.
-    #
-    # See {Embedded#compile} for keyword arguments.
-    #
-    # @example
-    #   Sass.compile('style.scss')
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see Embedded#compile
     def compile(path, **kwargs)
       instance.compile(path, **kwargs)
     end
 
-    # The global {.compile_string} method.
-    #
-    # This instantiates a global {Embedded} instance and calls {Embedded#compile_string}.
-    #
-    # See {Embedded#compile_string} for keyword arguments.
-    #
-    # @example
-    #   Sass.compile_string('h1 { font-size: 40px; }')
     # @return [CompileResult]
     # @raise [CompileError]
+    # @see Embedded#compile_string
     def compile_string(source, **kwargs)
       instance.compile_string(source, **kwargs)
     end
 
-    # The global {.info} method.
-    #
-    # This instantiates a global {Embedded} instance and calls {Embedded#info}.
+    # @return [String]
+    # @see Embedded#info
     def info
       instance.info
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sass-embedded
 version: !ruby/object:Gem::Version
-  version: 1.0.8
+  version: 1.0.9
 platform: ruby
 authors:
 - なつき
@@ -177,8 +177,8 @@ homepage: https://github.com/ntkme/sass-embedded-host-ruby
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://www.rubydoc.info/gems/sass-embedded/1.0.8
-  source_code_uri: https://github.com/ntkme/sass-embedded-host-ruby/tree/v1.0.8
+  documentation_uri: https://www.rubydoc.info/gems/sass-embedded/1.0.9
+  source_code_uri: https://github.com/ntkme/sass-embedded-host-ruby/tree/v1.0.9
   funding_uri: https://github.com/sponsors/ntkme
 post_install_message: 
 rdoc_options: []