lib/jsrb/base.rb in jsrb-0.2.0 vs lib/jsrb/base.rb in jsrb-0.2.1

@@ -1,20 +1,38 @@
 # frozen_string_literal: true
 
 module Jsrb
+  # Base is a centralized class for Jsrb template.
+  # `jsrb`, accessed from views (i.e. `*.js.jsrb` files), is an instance of Jsrb::Base.
+  #
+  # Jsrb::Base provides some utilities to push statements,
+  # construct expressions and generate the final JavaScript code,
+  # with preserving a statement context to build the abstract syntax tree.
   class Base
     def initialize
       @context = JSStatementContext.new
     end
 
+    #
+    # Generates executable JavaScript code from current context.
+    #
+    # @return [String] generated executable JavaScript code
     def generate_code
       generator = self.class.code_generator_class.new
       generator.call type: 'Program',
                      sourceType: 'script',
                      body: @context.stacks.first
     end
 
+    #
+    # Pushes a VariableDeclaration to the current context
+    # and returns an access to created identifier.
+    #
+    # @param optional [Symbol] name a name of identifier, autogenerated if not specified.
+    # @yield optional block for initializer
+    # @yieldreturn an initializer expression (optional)
+    # @return [Jsrb::ExprChain] the expression that represents constructed new identifier
     def var!(id = nil)
       id ||= @context.gen_var_name!
       if block_given?
         raw_expr = yield
         val = raw_expr.is_a?(ExprChain) ? raw_expr : expr(@context.ruby_to_js_ast(raw_expr))
@@ -23,30 +41,59 @@
         expr.as_variable_declaration!(id)
       end
       expr.member!(id)
     end
 
+    #
+    # Constructs a new conditional chain that **pushes an IfStatement** to the current context
+    # after the chain ended.
+    #
+    # @param [Jsrb::ExprChain, convertible ruby values] cond_expr an expression for the test
+    # @yield new context block for the consequent case
+    # @return [Jsrb::CondChain] condition chainable instance
     def if!(cond_expr, &block)
       CondChain.new(@context, false).elsif(cond_expr, &block)
     end
 
+    #
+    # Constructs a new conditional chain that **returns a conditional expression** after the chain ended.
+    #
+    # @param [Jsrb::ExprChain, convertible ruby values] cond_expr an expression for the test
+    # @yield new context block for the consequent case
+    # @return [Jsrb::CondChain] condition chainable instance
     def if(cond_expr, &block)
       CondChain.new(@context, true).elsif(cond_expr, &block)
     end
 
+    #
+    # Constructs a new expression chain with a given JavaScript AST node.
+    #
+    # @param optional [convertible ruby values] object represents JavaScript expression AST node
+    # @return [Jsrb::ExprChain] chainable instance
     def expr(object = nil)
       @context.new_expression(object)
     end
 
     class << self
-      def code_generator_class
-        @code_generator_class ||= Object.const_get(code_generator)
-      end
-
+      #
+      # Shows JavaScript generator class name, 'Jsrb::NotFastGenerator' by default.
+      #
+      # ### **Help wanted!**
+      #
+      # *Jsrb::NotFastGenerator uses ExecJS and escodegen to generate JavaScript.
+      # It could be more efficient and get better error messages if you
+      # rewrite in Ruby*.
+      #
       def code_generator
         @code_generator || 'Jsrb::NotFastGenerator'
       end
 
       attr_writer :code_generator
+
+      private
+
+      def code_generator_class
+        @code_generator_class ||= Object.const_get(code_generator)
+      end
     end
   end
 end