   constructor: (@method,@locals,@stack) ->
     @pc = 0
 
+# Contains all the mutable state of the Java program.
 class root.RuntimeState
   constructor: (@print, @async_input, @read_classfile) ->
     @classes = {}
-    # we have a dud object because pointers should never be zero
-    @heap = [null]
-    # for interned strings and string literals
+    @heap = [null] # We have a dud object because pointers should never be zero.
     @string_pool = {}
     @string_redirector = {}
-    # map zip descriptor ints to descriptor objects.
     @zip_descriptors = [null]
 
+  # Init the first class, and put the command-line args on the stack for use by
+  # its main method.
   initialize: (class_name, initial_args) ->
     args = @set_obj(c2t('[Ljava/lang/String;'),(@init_string(a) for a in initial_args))
     @meta_stack = [new root.StackFrame(null,[],[args])]  # start with a bogus ground state
     @class_lookup c2t class_name
 
-  # string stuff
+  # Convert a Java String object into an equivalent JS one.
   jvm2js_str: (jvm_str) ->
     @jvm_carr2js_str(jvm_str.fields.value, jvm_str.fields.offset, jvm_str.fields.count)
+  # Convert :count chars starting from :offset in a Java character array into a
+  # JS string
   jvm_carr2js_str: (arr_ref, offset, count) ->
     carr = @get_obj(arr_ref).array
     (util.bytes2str carr).substr(offset ? 0, count)
+  # Convert references to strings in the constant pool to the heap address of
+  # an interned String.
   string_redirect: (oref,cls) ->
     key = "#{cls}::#{oref}"
     cdata = @class_lookup(c2t(cls))

    @push null if field_spec.type in ['J','D']

  # static stuff
  static_get:(field_spec) ->
    f = @field_lookup(field_spec)
    obj = @get_obj @class_lookup(f.class_type, true)
    val = obj.fields[f.name]


  cl: (idx) -> @curr_frame().locals[idx]
  put_cl: (idx,val) -> @curr_frame().locals[idx] = val
  # Category 2 values (longs, doubles) take two slots in Java. Since we only
  # need one slot to represent a double in JS, we pad it with a null.
  put_cl2: (idx,val) -> @put_cl(idx,val); @put_cl(idx+1,null)

  push: (args...) ->
    cs = @curr_frame().stack
    Array::push.apply cs, args
  pop: () -> @curr_frame().stack.pop()
  pop2: () -> @pop(); @pop() # For category 2 values.

  # Program counter manipulation.
  curr_pc: ()   -> @curr_frame().pc
  goto_pc: (pc) -> @curr_frame().pc = pc
  inc_pc:  (n)  -> @curr_frame().pc += n

  # Heap manipulation.
  get_obj: (oref) ->
    java_throw @, 'java/lang/NullPointerException', '' unless @heap[oref]?
    @heap[oref]
