Add some more documentation to parser.rb

adambeynon · adambeynon · commit 617e72e57253 · 2013-07-30T22:22:04.000+01:00
diff --git a/lib/opal/parser.rb b/lib/opal/parser.rb
@@ -6,15 +6,21 @@
 module Opal
   class Parser
 
+    # A fragment holds a string of generated javascript that will be written
+    # to the destination. It also keeps hold of the original sexp from which
+    # 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!
     class Fragment
-
+      # String of javascript this fragment holds
       attr_reader :code
 
       def initialize(code, sexp = nil)
         @code = code
         @sexp = sexp
       end
 
+      # In debug mode we may wish to include the original line as a comment
       def to_code
         if @sexp
           "/*:#{@sexp.line}*/#{@code}"
@@ -23,8 +29,9 @@ def to_code
         end
       end
 
+      # inspect the contents of this fragment, f("fooo")
       def inspect
-        "fragment(#{@code.inspect})"
+        "f(#{@code.inspect})"
       end
     end
 
@@ -51,8 +58,13 @@ def inspect
     # Statements which should not have ';' added to them.
     STATEMENTS = [:xstr, :dxstr]
 
+    # Final generated javascript for this parser
     attr_reader :result
 
+    # Parse some ruby code to a string.
+    #
+    #     Opal::Parser.new.parse("1 + 2")
+    #     # => "(function() {....})()"
     def parse(source, options = {})
       @sexp = Grammar.new.parse(source, options[:file])
       @line     = 1
@@ -83,6 +95,7 @@ def parse(source, options = {})
       @result = source_map_comment + version_comment + file_comment + code
     end
 
+    # Always at top of generated file to show current opal version
     def version_comment
       "/* Generated by Opal #{Opal::VERSION} */\n"
     end
@@ -168,6 +181,13 @@ def mid_to_jsid(mid)
       end
     end
 
+    # Converts a ruby lvar/arg name to a js identifier. Not all ruby names
+    # are valid in javascript. A $ suffix is added to non-valid names.
+    def lvar_to_js(var)
+      var = "#{var}$" if RESERVED.include? var.to_s
+      var.to_sym
+    end
+
     # Used to generate a unique id name per file. These are used
     # mainly to name method bodies for methods that use blocks.
     #
@@ -747,10 +767,7 @@ def process_iter(sexp, level)
     # s(:args, parts...) => ["a", "b", "break$"]
     def js_block_args(sexp)
       sexp.map do |arg|
-        a = arg[1].to_sym
-        a = "#{a}$".to_sym if RESERVED.include? a.to_s
-        @scope.add_arg a
-        a
+        @scope.add_arg lvar_to_js(arg[1])
       end
     end
 
@@ -1025,25 +1042,20 @@ def process_class(sexp, level)
        code, fragment("\n#@indent})", sexp), fragment("(", sexp), base, fragment(", ", sexp), sup, fragment(")", sexp)]
     end
 
-    # s(:sclass, recv, body)
+    # Singleton class syntax. Runs body in context of singleton_class.
+    # s(:sclass, recv, body) => (function() { ... }).call(recv.$singleton_class())
     def process_sclass(sexp, level)
-      recv = sexp[0]
-      body = sexp[1]
-      code = []
+      recv, body, code = sexp[0], sexp[1], []
 
       in_scope(:sclass) do
         @scope.add_temp "__scope = #{current_self}._scope"
         @scope.add_temp "def = #{current_self}._proto"
 
-        body = process body, :stmt
-        code << @scope.to_vars << body
+        code << @scope.to_vars << process(body, :stmt)
       end
 
-      result = []
-      result << fragment("(function(){", sexp) << code
-      result << fragment("}).call(", sexp)
-      result << process(recv, :expr) << fragment(".$singleton_class())", sexp)
-      result
+      [f("(function(){", sexp), code, f("}).call(", sexp),
+       process(recv), f(".$singleton_class())", sexp)]
     end
 
     # s(:module, cid, body)
@@ -1095,6 +1107,7 @@ def process_module(sexp, level)
 
     # undef :foo
     # => delete MyClass.prototype.$foo
+    # FIXME: we should be setting method to a stub method here
     def process_undef(sexp, level)
       fragment("delete #{ @scope.proto }#{ mid_to_jsid sexp[0][1].to_s }", sexp)
     end
@@ -1276,6 +1289,7 @@ def process_self(sexp, level)
     # Returns the current value for 'self'. This will be native
     # 'this' for methods and blocks, and the class name for class
     # and module bodies.
+    # s(:self) => self or this or class name
     def current_self
       if @scope.class_scope?
         @scope.name
@@ -1286,19 +1300,25 @@ def current_self
       end
     end
 
+    # true literal
+    # s(:true) => true
     def process_true(sexp, level)
       fragment("true", sexp)
     end
 
+    # false literal
+    # s(:false) => false
     def process_false(sexp, level)
       fragment("false", sexp)
     end
 
+    # nil literal
+    # s(:nil) => nil
     def process_nil(sexp, level)
       fragment("nil", sexp)
     end
 
-    # s(:array [, sexp [, sexp]])
+    # s(:array [, sexp [, sexp]]) => [...]
     def process_array(sexp, level)
       return [fragment("[]", sexp)] if sexp.empty?
 
diff --git a/lib/opal/target_scope.rb b/lib/opal/target_scope.rb
@@ -168,6 +168,7 @@ def add_proto_ivar(ivar)
 
     def add_arg(arg)
       @args << arg unless @args.include? arg
+      arg
     end
 
     def add_local(local)
