Service Annotations

Note: This documentation is now self-hosted! Documentation for the latest release can be found here.

Service/RPC Annotations

Annotations use the google closure compiler syntax to

• describe the service
• validate RPC inputs
  • cast to correct type
  • enforce required (non-optional) inputs
  • uniform error reporting for invalid inputs (to the end user)
• populate the "help" messages for the end user
• make your code more readable and maintainable

Service Annotations

An annotation tagged with @service will be used to describe the Service and is shown to the user when getting help about the call <service> <RPC> block without any RPC set. An example is provided below.

/**
 * The IEXTrading Service provides access to real-time and historical stock price data.
 * For more information, check out https://iextrading.com/developer.
 *
 * Terms of use: https://iextrading.com/api-exhibit-a
 * @service
 */

RPC Annotations

RPC annotations can be used for RPC input validation and generating help messages for the user. An example of an annotation block for the city RPC from the geolocation service is shown below.

/** 
 * Get the name of the city nearest to the given latitude and longitude.
 *
 * @param {Latitude} latitude latitude of the target location
 * @param {Longitude} longitude longitude of the target location
 * @returns {String} city name
 */
GeoLocationRPC.city = function (latitude, longitude) {

Annotation blocks should be close to the RPC/function definition.

Read more: Annotations Guide

Essential Tags

• @param {Type} name description sentence
  • optional param: @param {Type=} name description sentence
• @returns

Supported Types

When both JavaScript and NetsBlox types exist, the types are specified using the JavaScript type. For example, Array is used instead of List.

• Number
• BoundedNumber<min,max>
• Latitude
• Longitude
• String
• Array
• Date
• Object: which is only used for defining structured data (list of key-value pairs)