API Generator

This is some documentation of the new API generator tool. The purpose of the tool is to automatically generate API metadata in a format that can be consumed by other tools. Simple use cases are:

• documentation generator
• test coverage
• syntax helpers for IDEs like Textmate
• something else with a wow factor you’ve yet to create

This is accomplished by comment annotations within the source code. The annotations can go any any normal source file (C, C++, Javascript, etc) in either a short-form or long-form comment block.

We’re going to use 3 tags which are Javadocs-like format:

• @tiapi – this tag will describe the main entrypoint of the api. it must come before the other tags lexically
• @tiarg – this tag is optional and describes one argument that the api takes. you can have multiple of these per argument for a @tiapi
• @tiresult – this tag is optional and describes the return metadata for a @tiapi

@tiapi

The following are properties:

• name – the name of the method. Required. This should be the full path to the API excluding Titanium.
• method – True if this is a method.
• property – True if this is a property.
• since – The version that this API was first introduced and made available.

@tiarg

The following are properties:

• for – the @tiarg name that this argument is for.
• name – name of the argument (for reference purposes only)
• type – the data type (should map to Kroll data types)
• optional – True if the argument is optional. defaults to False.

@tiresult

The following are properties:

• for – the @tiarg name that this argument is for.
• type – the data type (should map to Kroll data types)

Example:

/**
 * @tiapi(method=True,name=Analytics.addEvent) send an analytics event associated with the application
 * @tiarg(for=Analytics.addEvent,name=event,type=string,optional=false) name of the event
 * @tiarg(for=Analytics.addEvent,name=data,type=any,optional=true) optional data to associate with event
 * @tiresult(for=Analytics.addEvent,type=void) returns void
 */

Invoking from Scons

You invoke the API generator from the Titanium scons.

scons apicoverage

This will place a file named apicoverage.json in the build/<osname> directory.