opal/corelib/runtime.js in opal-0.9.0.rc1 vs opal/corelib/runtime.js in opal-0.9.0

@@ -112,24 +112,28 @@
 
   // Create a new constants scope for the given class with the given
   // base. Constants are looked up through their parents, so the base
   // scope will be the outer scope of the new klass.
   //
-  Opal.create_scope = function(base, klass, id) {
+  // @param base_scope [$$scope] the scope in which the new scope should be created
+  // @param klass      [Class]
+  // @param id         [String, null] the name of the newly created scope
+  //
+  Opal.create_scope = function(base_scope, klass, id) {
     var const_alloc = function() {};
-    var const_scope = const_alloc.prototype = new base.constructor();
+    var const_scope = const_alloc.prototype = new base_scope.constructor();
 
     klass.$$scope       = const_scope;
-    klass.$$base_module = base.base;
+    klass.$$base_module = base_scope.base;
 
     const_scope.base        = klass;
     const_scope.constructor = const_alloc;
     const_scope.constants   = [];
 
     if (id) {
-      Opal.cdecl(base, id, klass);
-      const_alloc.displayName = id+"_alloc";
+      Opal.cdecl(base_scope, id, klass);
+      const_alloc.displayName = id+"_scope_alloc";
     }
   }
 
   // A `class Foo; end` expression in ruby is compiled to call this runtime
   // method which either returns an existing class of the given name, or creates
@@ -147,16 +151,17 @@
   // The `base` is the current `self` value where the class is being created
   // from. We use this to get the scope for where the class should be created.
   // If `base` is an object (not a class/module), we simple get its class and
   // use that as the base instead.
   //
-  // @param [Object] base where the class is being created
-  // @param [Class] superklass superclass of the new class (may be null)
-  // @param [String] id the name of the class to be created
-  // @param [Function] constructor function to use as constructor
-  // @return [Class] new or existing ruby class
+  // @param base        [Object] where the class is being created
+  // @param superklass  [Class,null] superclass of the new class (may be null)
+  // @param id          [String] the name of the class to be created
+  // @param constructor [Function] function to use as constructor
   //
+  // @return new [Class]  or existing ruby class
+  //
   Opal.klass = function(base, superklass, id, constructor) {
     var klass, bridged, alloc;
 
     // If base is an object, use its class
     if (!base.$$is_class && !base.$$is_module) {
@@ -339,13 +344,13 @@
   // generated instead (cannot have a class and module of same name in same base).
   //
   // Otherwise, a new module is created in the base with the given name, and that
   // new instance is returned back (to be referenced at runtime).
   //
-  // @param [RubyModule or Class] base class or module this definition is inside
-  // @param [String] id the name of the new (or existing) module
-  // @return [RubyModule]
+  // @param  base [Module, Class] class or module this definition is inside
+  // @param  id [String] the name of the new (or existing) module
+  // @return [Module]
   //
   Opal.module = function(base, id) {
     var module;
 
     if (!base.$$is_class && !base.$$is_module) {
@@ -694,12 +699,22 @@
 
     return klass;
   }
 
 
-  // constant assign
+  // Constant assignment, see also `Opal.cdecl`
   //
+  // @param base_module [Module, Class] the constant namespace
+  // @param name        [String] the name of the constant
+  // @param value       [Object] the value of the constant
+  //
+  // @example Assigning a namespaced constant
+  //   self::FOO = 'bar'
+  //
+  // @example Assigning with Module#const_set
+  //   Foo.const_set :BAR, 123
+  //
   Opal.casgn = function(base_module, name, value) {
     function update(klass, name) {
       klass.$$name = name;
 
       for (name in klass.$$scope) {
@@ -712,10 +727,11 @@
     }
 
     var scope = base_module.$$scope;
 
     if (value.$$is_class || value.$$is_module) {
-      // only checking _Object prevents setting a const on an anonymous class that has a superclass that's not Object
+      // Only checking _Object prevents setting a const on an anonymous class
+      // that has a superclass that's not Object
       if (value.$$is_class || value.$$base_module === _Object) {
         value.$$base_module = base_module;
       }
 
       if (value.$$name === nil && value.$$base_module.$$name !== nil) {