Explain this confusing dojo tutorial syntax for declare

Question

I am reading the syntax for using dojo's declare for class creation. The description is confusing:

The declare function is defined in the dojo/_base/declare module. declare accepts three arguments: className, superClass, and properties.
ClassName

The className argument represents the name of the class, including the namespace, to be created. Named classes are placed within the global scope. The className can also represent the inheritance chain via the namespace.
Named Class

// Create a new class named "mynamespace.MyClass"
declare("mynamespace.MyClass", null, {

    // Custom properties and methods here

});

A class named mynamespace.MyClass is now globally available within the application.

Named classes should only be created if they will be used with the Dojo parser. All other classes should omit the className parameter.
"Anonymous" Class

// Create a scoped, anonymous class
var MyClass = declare(null, {

    // Custom properties and methods here

});

The MyClass is now only available within its given scope.
SuperClass(es)

The SuperClass argument can be null, one existing class, or an array of existing classes. If a new class inherits from more than one class, the first class in the list will be the base prototype, the rest will be considered "mixins".
Class with No Inheritance

var MyClass = declare(null, {

    // Custom properties and methods here

});

null signifies that this class has no classes to inherit from.
Class Inheriting from Another Class

var MySubClass = declare(MyClass, {

    // MySubClass now has all of MyClass's properties and methods
    // These properties and methods override parent's

});

The syntax is exactly the same for creating a non-named class and a class with no superclass:

var MyClass = declare(null, {
    // Custom properties and methods here  
});

I expect the syntax for a class without any super class and without any name to be like this:

var MyClass = declare(null, null, {
    // Custom properties and methods here  
});

I am coming from a typed language background, so perhaps I've misunderstood how this works in JavaScript. I fail to understand how someone reading the code (without any comments) would know the difference between the two, if the tutorials syntax is correct.

I would have expected the syntax to be something like this:

/*class without a name:*/ declare(null, SuperClass, {})

/*class without a name or super class:*/ declare(null, null, {})

/*class with a name but no super class:*/ declare("ClassName", null, {})

Maybe this is verbose, but at least it is easy to tell what each parameter is for.

Answer 1

Well, consider it an overloaded constructor:

// class with a name
declare(className: String, superClass: Array, classDeclaration: Object);

// class without a name
declare(superClass: Array, classDeclaration: Object);

Use an empty array [] or null for no superClass.

N.B.: As of Dojo 1.8, there is no need for named classes, because dojo/parser can use a module id (mid, e.g. "mynamespace/MyClass") for instantiation. I consider named classes to be obsolete and against code maintainability.