Document some parts of lib

adambeynon · adambeynon · commit 016887a729c2 · 2014-11-28T17:49:04.000Z
diff --git a/lib/opal/compiler.rb b/lib/opal/compiler.rb
@@ -4,10 +4,45 @@
 require 'opal/nodes'
 
 module Opal
+  # Compile a string of ruby code into javascript.
+  #
+  # @example
+  #
+  #     Opal.compile "ruby_code"
+  #     # => "string of javascript code"
+  #
+  # @see [Opal::Compiler.new] for compiler options
+  #
+  # @param source [String] ruby source
+  # @param options [Hash] compiler options
+  # @return [String] javascript code
+  #
   def self.compile(source, options = {})
     Compiler.new(source, options).compile
   end
 
+  # [Opal::Compiler] is the main class used to compile ruby to javascript code.
+  # This class uses [Opal::Parser] to gather the sexp syntax tree for the ruby
+  # code, and then uses [Opal::Node] to step through the sexp to generate valid
+  # javascript.
+  #
+  # @example
+  #
+  #     Opal::Compiler.new("ruby code").compile
+  #     # => "javascript code"
+  #
+  # @example accessing result
+  #
+  #     compiler = Opal::Compiler.new("ruby_code")
+  #     compiler.compile
+  #     compiler.result # => "javascript code"
+  #
+  # @example SourceMaps
+  #
+  #     compiler = Opal::Compiler.new("")
+  #     compiler.compile
+  #     compiler.source_map # => #<SourceMap:>
+  #
   class Compiler
     # Generated code gets indented with two spaces on each scope
     INDENT = '  '
@@ -48,7 +83,11 @@ def self.compiler_option(name, default_value, options = {})
     # are operators compiled inline
     compiler_option :inline_operators, false, :as => :inline_operators?
 
-    attr_reader :result, :fragments
+    # @return [String] The compiled ruby code
+    attr_reader :result
+
+    # @return [Array] all [Opal::Fragment] used to produce result
+    attr_reader :fragments
 
     # Current scope
     attr_accessor :scope
@@ -67,6 +106,8 @@ def initialize(source, options = {})
     end
 
     # Compile some ruby code to a string.
+    #
+    # @return [String] javascript code
     def compile
       @parser = Parser.new
 
@@ -78,11 +119,20 @@ def compile
       @result = @fragments.map(&:code).join('')
     end
 
+    # Returns a source map that can be used in the browser to map back to
+    # original ruby code.
+    #
+    # @param source_file [String] optional source_file to reference ruby source
+    # @return [Opal::SourceMap]
     def source_map(source_file = nil)
       Opal::SourceMap.new(@fragments, source_file || self.file)
     end
 
-    # Any helpers required by this file
+    # Any helpers required by this file. Used by [Opal::Nodes::Top] to reference
+    # runtime helpers that are needed. These are used to minify resulting
+    # javascript by keeping a reference to helpers used.
+    #
+    # @return [Set<Symbol>]
     def helpers
       @helpers ||= Set.new([:breaker, :slice])
     end
diff --git a/lib/opal/erb.rb b/lib/opal/erb.rb
@@ -2,11 +2,33 @@
 
 module Opal
   module ERB
+    # Compile ERB code into javascript.
+    #
+    # [Opal::ERB] can be used to compile [ERB] templates into javascript code.
+    # This module uses the [Opal::Compiler] internally.
+    #
+    # Compiled templates, when run in a javascript environment, will appear
+    # under the `Template` namespace, and can be accessed as:
+    #
+    #     Template['template_name'] # => template instance
+    #
+    # @example
+    #
+    #     source = "<div><%= @content %></div>"
+    #
+    #     Opal::ERB.compile source, "my_template.erb"
+    #
+    # @param source [String] erb content
+    # @param file_name [String] filename for reference in template
+    # @return [String] javascript code
+    #
     def self.compile(source, file_name = '(erb)')
       Compiler.new(source, file_name).compile
     end
 
     class Compiler
+      BLOCK_EXPR = /\s+(do|\{)(\s*\|[^|]*\|)?\s*\Z/
+
       def initialize(source, file_name = '(erb)')
         @source, @file_name, @result = source, file_name, source
       end
@@ -31,8 +53,6 @@ def fix_quotes(result)
         result.gsub '"', '\\"'
       end
 
-      BLOCK_EXPR = /\s+(do|\{)(\s*\|[^|]*\|)?\s*\Z/
-
       def require_erb(result)
         'require "erb";'+result
       end
diff --git a/lib/opal/fragment.rb b/lib/opal/fragment.rb
@@ -4,16 +4,27 @@ module Opal
   # it was generated. Using this sexp, when writing fragments in order, a
   # mapping can be created of the original location => target location,
   # aka, source-maps!
+  #
+  # These are generated by nodes, so will not have to create directly.
   class Fragment
     # String of javascript this fragment holds
+    # @return [String]
     attr_reader :code
 
+    # Create fragment with javascript code and optional original [Opal::Sexp].
+    #
+    # @param code [String] javascript code
+    # @param sexp [Opal::Sexp] sexp used for creating fragment
     def initialize(code, sexp = nil)
       @code = code.to_s
       @sexp = sexp
     end
 
-    # In debug mode we may wish to include the original line as a comment
+    # In debug mode we may wish to include the original line and comment in
+    # a javascript comment.
+    #
+    # @deprecated
+    #
     def to_code
       if @sexp
         "/*:#{@sexp.line}:#{@sexp.column}*/#{@code}"
@@ -22,18 +33,19 @@ def to_code
       end
     end
 
-    # debug:
-    # alias code to_code
-
-    # inspect the contents of this fragment, f("fooo")
+    # Inspect the contents of this fragment, f("fooo")
     def inspect
       "f(#{@code.inspect})"
     end
 
+    # Original line this fragment was created from
+    # @return [Integer, nil]
     def line
       @sexp.line if @sexp
     end
 
+    # Original column this fragment was created from
+    # @return [Integer, nil]
     def column
       @sexp.column if @sexp
     end
diff --git a/lib/opal/parser.rb b/lib/opal/parser.rb
@@ -4,10 +4,33 @@
 require 'opal/parser/parser_scope'
 
 module Opal
+  # [Parser] is used to parse a string of ruby code into a tree of [Opal::Sexp]
+  # to represent the given ruby source code. The [Opal::Compiler] used this tree
+  # of sexp expressions, and turns them into the resulting javascript code.
+  #
+  # Usually, you would want to use [Opal::Compiler] directly, but this class
+  # can be useful for debugging the compiler, as well as building tools around
+  # the opal compiler to view the code structure.
+  #
+  # Invalid ruby code will raise an exception.
+  #
+  # @example
+  #
+  #     Opal::Parser.new.parse "ruby code"
+  #     # => sexp tree
+  #
   class Parser < Racc::Parser
 
     attr_reader :lexer, :file, :scope
 
+    # Parse the given ruby source. An optional file can be given which is used
+    # for file context for some ruby expressions (e.g. `__FILE__`).
+    #
+    # If the given ruby code is not valid ruby, then an error will be raised.
+    #
+    # @param source [String] ruby source code
+    # @param file [String] filename for context of ruby code
+    # @return [Opal::Sexp] sexp expression tree representing ruby code
     def parse(source, file = '(string)')
       @file = file
       @scopes = []
diff --git a/lib/opal/parser/lexer.rb b/lib/opal/parser/lexer.rb
@@ -2,6 +2,23 @@
 require 'opal/parser/keywords'
 
 module Opal
+  # [Opal::Lexer] is used by [Opal::Parser] to step through ruby code, and
+  # returning tokens representing each chunk of ruby code.
+  #
+  # Tokens are in the form:
+  #
+  #     [token, [value, location]]
+  #
+  # where `location` is in the form `[line_number, column_number]`. The location
+  # data can be used to produce source maps in the compiler. Tokens are
+  # generally ruby symbols, and the value will always be a string value.
+  #
+  # The main method used by the parser is `next_token`, which is called
+  # repeatedly until a token of value `false` is returned, which indicated the
+  # EOF has been reached.
+  #
+  # Generally this class is only used by [Opal::Parser] directly.
+  #
   class Lexer
 
     STR_FUNC_ESCAPE = 0x01
@@ -31,6 +48,16 @@ class Lexer
     attr_accessor :yylval
     attr_accessor :parser
 
+    # Create a new instance using the given ruby code and filename for
+    # reference.
+    #
+    # @example
+    #
+    #     Opal::Lexer.new("ruby code", "my_file.rb")
+    #
+    # @param source [String] ruby code to lex
+    # @param file [String] filename of given ruby code
+    #
     def initialize(source, file)
       @lex_state  = :expr_beg
       @cond       = 0
@@ -48,6 +75,26 @@ def initialize(source, file)
       @start_of_lambda = nil
     end
 
+    # Returns next token from source input stream.
+    #
+    # Token in form:
+    #
+    #     [token, [value, [source_line, source_column]]]
+    #
+    # @return [Array]
+    #
+    def next_token
+      token     = self.yylex
+      value     = self.yylval
+      location  = [@tok_line, @tok_column]
+
+      # once location is stored, ensure next token starts in correct place
+      @tok_column = @column
+      @tok_line = @line
+
+      [token, [value, location]]
+    end
+
     def has_local?(local)
       parser.scope.has_local?(local.to_sym)
     end
@@ -151,18 +198,6 @@ def line=(line)
       @line = @tok_line = line
     end
 
-    def next_token
-      token     = self.yylex
-      value     = self.yylval
-      location  = [@tok_line, @tok_column]
-
-      # once location is stored, ensure next token starts in correct place
-      @tok_column = @column
-      @tok_line = @line
-
-      [token, [value, location]]
-    end
-
     def new_strterm(func, term, paren)
       { :type => :string, :func => func, :term => term, :paren => paren }
     end
@@ -600,6 +635,7 @@ def process_identifier(matched, cmd_start)
       return matched =~ /^[A-Z]/ ? :tCONSTANT : :tIDENTIFIER
     end
 
+    # Does the heavy lifting for `next_token`.
     def yylex
       @yylval = ''
       @space_seen = false
diff --git a/lib/opal/parser/parser_scope.rb b/lib/opal/parser/parser_scope.rb
@@ -6,6 +6,9 @@ class ParserScope
     attr_reader :locals
     attr_accessor :parent
 
+    # Create new parse scope. Valid types are :block, :class, :module, :def.
+    #
+    # @param type [Symbol] scope type
     def initialize(type)
       @block  = type == :block
       @locals = []
diff --git a/lib/opal/parser/sexp.rb b/lib/opal/parser/sexp.rb
@@ -1,4 +1,11 @@
 module Opal
+  # [Opal::Sexp] is used to build up the syntax tree inside [Opal::Parser]. The
+  # compiler then steps through the sexp trees to generate the javascript code.
+  #
+  # For example, an array of integers `[1, 2]` might be represented by:
+  #
+  #     s(:array, s(:int, 1), s(:int, 2))
+  #
   class Sexp
 
     attr_reader :array
@@ -72,4 +79,3 @@ def pretty_inspect
     alias to_s inspect
   end
 end
-
diff --git a/lib/opal/sprockets/environment.rb b/lib/opal/sprockets/environment.rb
@@ -3,20 +3,12 @@
 require 'opal/sprockets/erb'
 
 module Opal
-  # Proccess using Sprockets
-  #
-  #   Opal.process('opal-jquery')   # => String
+  # @deprecated
   def self.process asset
     Environment.new[asset].to_s
   end
 
-  # Environment is a subclass of Sprockets::Environment which already has our opal
-  # load paths loaded. This makes it easy for stand-alone rack apps, or test runners
-  # that have opal load paths ready to use. You can also add an existing gem's lib
-  # directory to our load path to use real gems inside your opal environment.
-  #
-  # If you are running rails, then you just need opal-rails instead, which will
-  # do this for you.
+  # @deprecated
   class Environment < ::Sprockets::Environment
     def initialize *args
       warn "WARNING: Opal::Sprockets::Environment is deprecated. "\
diff --git a/lib/opal/util.rb b/lib/opal/util.rb
@@ -2,13 +2,18 @@ module Opal
   module Util
     extend self
 
-    # Used for uglifying source to minify
+    # Used for uglifying source to minify.
+    #
+    #     Opal::Util.uglify("javascript contents")
+    #
+    # @param str [String] string to minify
+    # @return [String]
     def uglify(str)
       uglifyjs = DigestSourceCommand.new(:uglifyjs, nil, ' (install with: "npm install -g uglify-js")')
       uglifyjs.digest(str)
     end
 
-    # Gzip code to check file size
+    # Gzip code to check file size.
     def gzip(str)
       gzip = DigestSourceCommand.new(:gzip, '-f', ', it is required to produce the .gz version')
       gzip.digest(str)
