...
Type | Notes |
|---|---|
Object | Please don't misuse. We wish to emphasize the use of strong types. |
Titanium.XX.XX | This is shorthand to signify the types that are defined within the documentation. In fact, they don't have to be the |
Dictionary<[type]> | A special type+syntax indicating a dictionary – i.e., an object literal – whose members can be the properties of the specified [type]. Example: |
Callback<[type]> | A special type+syntax indicating a function used as a callback, whose single callback argument (the info passed to the callback) is of type [type], where [type] can be a type that you define elsewhere. We'll see examples of this in the special section on callbacks. The angle bracket notation is optional: |
...
Additionally, other "pseudo-types" (for lack of a better term) may be defined inside the documents as stand-ins for things like callback arguments, object literals that are passed as parameters, or objects that implement a particular interface. We'll see examples of this in the special sections on callbacks and object literals and interfaces.
Inheritance
The specification supports what might be called "multiple documentation inheritance", whereby a Titanium type that is being documented (i.e., a proxy or module) has an extends property that can be set to a single qualified type name or an array of type names, thereby giving the child type all of the method, property and event documentation defined in the super types. Example:
...
Key | Notes | Example |
|---|---|---|
name | A fully-qualified name for the type | |
summary | A short, "one-liner" summary of the type, in Markdown format. Keep it short, as it will often be generated next to the type name in lists, for example. Deeper information about the type should go into the | |
description | (Optional) Free-form , longer format text description of the Type, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be | See Free-Form Text Values below. |
createable | (Optional) Applicable only to "proxy" types (types having | |
platforms | (Optional) Array of supported platforms. If missing, it is to be assumed that all platforms are supported. Note that | |
extends | (Optional). Either a single fully-qualified type name, or an array of fully-qualified type names from which the documented Type inherits. | |
excludes | (Optional). For excluding inherited methods, properties or events. Can have one or more of these members: | |
since | Indicates in which Titanium version the Type first appeared. Either a single value if the Type appeared at the same time on all platforms, or a dictionary object with keys per platform and values containing the relevant version number. NOTE: YAML will interpret values such as | |
deprecated | (Optional) A simple dictionary object with keys | |
osver | (Optional). Can be used to specify operating system version number requirements for the given type. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys | |
examples | (Optional). An array of objects wherein each element has | See #Code Examples below. |
methods | (Optional). An array of method definitions describing the type's methods. | See #Method Specification below. |
properties | (Optional). An array of property definitions describing the type's methods. | See #Property Specification below. |
events | (Optional). An array of event definitions describing the type's events. | See #Event Specification below. |
Our running example so far:
...
Key | Notes | Examples |
|---|---|---|
name | The method name. | |
summary | A short, "one-liner" summary of the method, in Markdown format. Keep it short, as it will often be generated next to the method name in lists, for example. Deeper information about the method should go into the | |
description | (Optional) Free-form , longer format text description of the method, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be | See Free-Form Text Values below. |
returns | (Optional). A dictionary object with | |
platforms | (Optional). Identical to the | |
since | (Optional). Identical to the | |
deprecated | (Optional) A simple dictionary object with keys | |
osver | (Optional). Can be used to specify operating system version number requirements for the given method. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys | |
examples | (Optional). Identical to the | See #Code Examples below. |
parameters | (Optional). An array of parameter definitions documenting the method parameters. | See #Method Parameter Specification below. |
Method Parameter Specification
...
Key | Notes | Examples |
|---|---|---|
name | The property name. | |
summary | A short, "one-liner" summary of the property, in Markdown format. Keep it short, as it will often be generated next to the property name in lists, for example. Deeper information about the property should go into the | |
description | (Optional) Free-form , longer format text description of the property, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be | See Free-Form Text Values below. |
type | A data type specifier indicating the type of the parameter, or an array of data type specifiers in case multiple types are allowed for the parameter. A view dimension is a typical use-case for the latter, since we support numeric values (interpreted as pixels) or string values ("auto", "10dp", etc.). | |
platforms | (Optional). Identical to the | |
since | (Optional). Identical to the | |
deprecated | (Optional) A simple dictionary object with keys | |
osver | (Optional). Can be used to specify operating system version number requirements for the given property. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys | |
examples | (Optional). Identical to the | See #Code Examples below. |
permission | (Optional). One of | |
availability | (Optional). When the property can be written to, in the sense that some of our proxy properties can only be set in the dictionary object passed to a | |
accessors | (Optional). Whether a getter and setter method exist for the property (true/false, default true). | |
optional | (Optional). Whether it's considered optional to have the property set in the object. The default is | |
value | (Optional). The fixed value of the property. Particularly useful to express that something is a constant, such as by setting | |
default | (Optional). The default value of a property. You can use this to set a specific value (such as 0) or free text explaining how the default value is determined. | |
Multiple property documentation definitions can be put together into a YAML sequence by following the same syntax as for multiple methods.
Our running example so far, which includes a sequence of property definitions:
...
Key | Notes | Examples |
|---|---|---|
name | The event name. | |
summary | A short, "one-liner" summary of the event, in Markdown format. Keep it short, as it will often be generated next to the event name in lists, for example. Deeper information about the event should go into the | |
description | (Optional) Free-form , longer format text description of the event, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be | See Free-Form Text Values below. |
extends | (Optional). Either a single fully-qualified type name, or an array of fully-qualified type names from which the event object inherits. As a convenience, this can be omitted and it will then be assumed that the event object extends | |
platforms | (Optional). Identical to the | |
since | (Optional). Identical to the | |
deprecated | (Optional) A simple dictionary object with keys | |
osver | (Optional). Can be used to specify operating system version number requirements for the given event. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys | |
properties | (Optional). A sequence of event listener object property definitions which describe the properties in the event object passed to a listener for this event. |
Multiple event documentation definitions can be put together into a YAML sequence by following the same syntax as for multiple methods.
Our running example so far, which includes a sequence of event definitions:
...
Key | Notes | Examples |
|---|---|---|
name | The property name. | |
summary | A short, "one-liner" summary of the property, in Markdown format. Please start summaries with a capital letter and end with a period. | |
type | A data type specifier indicating the type of the property, or an array of data type specifiers in case multiple types are allowed for the property. A view dimension is a typical use-case for the latter, since we support numeric values (interpreted as pixels) or string values ("auto", "10dp", etc.). | |
platforms | (Optional). Identical to the | |
deprecated | (Optional) A simple dictionary object with keys | |
For examples, see the YAML sample above in the #Event Specification.
Free-Form Text Values
Three of the YAML keys described in previous sections – summary, description and the example property of each member of an examples array – accept free-form text which will be processed by our scripts as Markdown. This section describes valid approaches to entering free-form text as values for YAML keys.
...
[type] should be replaced with the name of a type that you document simply for purposes of documenting this callback parameter. These can perhaps be thought of as pseudo-types, in the sense that they are only "being documented for the documentation", or to make the documentation complete.
The next section, #Documenting Object Literals and Interfaces, describes how to document these pseudo-types. For the time being, imagine you have defined a pseudo-type named ScreenshotResult to be used with the callback for Titanium.Media.takeScreenshot. In that case, the documentation for the parameters of takeScreenshot would look like this:
...
Object Literals
As the section on #Documenting Callbacks shows, there are some occasions when we wish to provide "strongly-typed documentation" for what are actually simple Javascript object literals with Java HashMap or Objective-C NSDictionary instances behind them. The single parameter accepted by callbacks is one good example; in that case, we wish to document which properties can be expected in the object literal passed to the callback, what data types should be expected for those properties, etc.
...
With YAML, you can document multiple types in a single documentation file simply by starting a new "document". You'll recall from #A Type Documentation is a YAML Document that a new document begins with three dashes (---) alone on a line. So if you wish to write documentation for a pseudo-type that is only used in one place, you can simply start a new YAML document at the bottom of the file.
...
If a pseudo-type is useful in multiple modules, it should go in a common/ folder which is at the root of the documentation directories, i.e., as a sibling to Titanium/. One example of this is the documentation definition for the Stream interface described in #Interfaces above. In that case, a file in common/ should exist – perhaps common/TiStream.yml – with contents similar to this example:
...
Markdown Links in Free-Form Text Values
As explained earlier, a few of the documentation YAML key values accept free-form text which is treated as Markdown. Backticks and double-brackets will no longer be used within these text blocks as indicators that links to type documentation should automatically be generated. Instead, Markdown shall be followed more closely. In Markdown, the backtick has no meaning with respect to linking – nor does a set of double square brackets.
...