Namespaces

Modified on Thursday, 24 June 2010 15:41 by Administrator — Categorized as: Uncategorized

In ECMAScript implementations 3 and prior (JavaScript 1.x for instance), the language doesn't provide formal support for namespaces (packages). Because of this, many developers and JavaScript frameworks implement custom ways of registering types within namespaces. For instance, consider this code fragment from Microsoft Ajax Library:


Type.registerNamespace("Sys.Net");

Sys.Net.WebRequestExecutor = function Sys$Net$WebRequestExecutor() { /// ... }

After registering the namespace Sys.Net, the type Sys.Net.WebRequestExecutor is considered as type WebRequestExecutor, living in the namespace Sys.Net.

In ECMADoc, every type discovered in the global (document) scope will be assigned a namespace. That is, all types in ECMADoc have a namespace. The default namespace that is always there and into which types with no namespace specifications are assigned is the Global namespace.

Because different developers have different ways of implementing namespace support, it is possible to define custom expressions that will cause ECMADoc to register a namespace with the parser. For more information, see parser configuration.

Namespace registration

In ECMADoc, there are two ways to register a namespace with the parser:

  1. Through the use of a custom language construct (such as Type.registerNamespace)
  2. Through the use of the @namespace token

Using a custom language construct

If the code for which you are generating the documentation already contains namespace information, this information can be picked up by the parser. Out of the box, ECMADoc supports the Type.registerNamespace("namespace") syntax. For information about adding a different custom language construct, consult the parser configuration page.

Using the @namespace token

Sometimes the code contains certain nested types that developer consider namespaces without explicitly 'registering' them with custom language constructs. To instruct ECMADoc to consider specific type prefixes as namespaces you can use the @namespace token. Note that @namespace tokens can only appear within @document tokens.

/**
 * @document
 * @namespace Aeon
 * @namespace Aeon.Utils
 */

This will cause the parser to create Aeon and Aeon.Utils namespaces, and types whose names begin with 'Aeon' or 'Aeon.Utils' will be assigned the corresponding namespaces.