Base files

Modified on Monday, 21 December 2009 08:36 by Administrator — Categorized as: Uncategorized

Base files provide API documentation for the built-in functionality provided by the ECMAScript implementation of the engine that a project uses. By default, the JavaScript base file will be added to new projects created with the GUI. You may choose to include them with the rest of the files in your project, but they are not required.

They are provided as a convenience, for completeness of the generated documentation. Because many JavaScript implementation provide the possibility to augment and modify the built-in types, such as Array, String, Date etc by adding and/or changing their prototype members, many JavaScript projects in fact do so, and as such this customizations may make it into the generated API documentation.

For instance, you may choose to add an additional method to the built-in Array class:


/**
 * Calls the supplied function on each of the elements in the array.
 * @param {Function} fx The function to call.
 * @param {Object} context The context object in which to call the function. Optional.
 */
Array.prototype.each = function Array$each(fx, context)
{
    for (var i = 0; i < this.length; i++)
    {
        var r = fx.call(context, this[i], i, this);
        if (r != undefined)
            this[i] = r;
    }

return this; }

Unless the base file is used, when the documentation is generated the Array class will appear as having only the each method (or whatever other members are defined on the Array class in the current project), without showing the full API of the built-in Array class. So to make sure the rest of the built-in types' API also makes it into the result documentation, these base files can be used.

Base file are located in the Resources/Base directory of the ECMADoc.

Array class, in a project that doesn't include the base file

In the example below, one of the files in the project extends the built-in Array class with an additional method 'each'. However, since there is no other information about the array, the HTML output that ECMADoc produces for this class is scarce and incomplete:

Image

Array class, in a project that includes the base file

In this second example, the method 'each' appears together will all other members of Array. The information about the Array is far more complete in this version.

Image