Metadata Comments

Metadata comments are comments that supply more information about the source code of an AeroScript program or library.

You can use top-level metadata comments to supply general information about an AeroScript program or library. For an example of top-level metadata comments, see the code sample that follows:

//! @summary Supplies more mathematical functions.
//! @author John Smith
//! @version 1.0.1

library function Square($value as real) as real
    return $value * $value
end

You can also use metadata comments to supply information about functions, properties, enums, or structs. The application uses the metadata comments about these items to generate documentation for them. That documentation comes into view in the autocomplete feature of the Programming module in Automation1 Studio. For an example of a metadata comment about a function, see the code sample that follows:

/*!
    @summary Makes the cube of a value.
    @argument $value The value to cube.
    @return The cube of the value.
*/
library function Cube($value as real) as real
    return $value * $value * $value
end

Metadata Comment Format

Metadata comments can be single-line or multi-line comments:

• Single-line metadata comments start with //! and terminate at the end of the line on which you specify them.
• Multi-line metadata comments start with /*! and end with */.

You can specify metadata comments as follows. Use only one of these options in your AeroScript program or library:

• Specify one single-line metadata comment that starts and terminates on the same line.
• Specify two or more single-line metadata comments on consecutive lines to combine their information.
• Specify one multi-line metadata comment.

For more information about single-line comments and multi-line comments, see Comments and Whitespace.

A metadata comment has one or more attributes. See the guidelines that follow:

• The name of an attribute starts with the @ character.
• The next character of the attribute name must be a letter (A-Z, a-z) or an underscore (_). After you specify this character, you can specify zero or more letters, digits (0-9), hyphens (-), underscores, and periods (.).
• The name of an attribute cannot contain spaces.
• Attribute names are case-sensitive. Thus, an attribute named @myAttribute is different from an attribute named @MyAttribute.
• You can use the same name to specify two or more attributes.

A metadata attribute can have an optional value that you include as:

• Text that you specify after the attribute name.
• Text that you specify until the next attribute name.
• Text that you specify at the end of the metadata comment.

The code sample that follows shows different types of metadata attributes:

//! @attribute-with-a-value The attribute value.
//! @attribute-without-a-value

In the value of the attribute, the compiler converts newline and tab characters into spaces. It also converts two or more spaces into one space. If the attribute value has too much whitespace, which includes spaces, tabs, and newline characters, the compiler removes it from the start and end of the attribute value.

If the compiler detects a metadata comment that is incorrect, it stops parsing the current line and starts to parse the next line. A metadata comment can be incorrect because of the problems that follow:

• An attribute name is invalid.
• You specified text before you specified an attribute.

Top-Level Metadata Comments

Use top-level metadata comments to supply information about an AeroScript program or library.

You must specify top-level metadata comments before other lines in the source code of an AeroScript program or library. A new line or a regular (non-metadata) comment must follow top-level metadata comments.

Recompile Program Automation Auto-Import Libraries

If you use the Auto-Import feature of the Program Automation module, you might receive compiler errors that include information about redefined functions, properties, enums, or structs. These compiler errors occur when you try to recompile Auto-Imported AeroScript libraries. To prevent these compiler errors, use top-level metadata comments in the Auto-Import libraries.

Each AeroScript library that you configure for the Auto-Import feature must contain a unique identifier. To include a unique identifier for each library, specify the @unique-id attribute in a top-level metadata comment. The @unique-id attribute must contain a value. Its value must be different in each library that is configured as an Auto-Import library. See the sample code that follows:

//! @unique-id MyLibrary
//! @version 0.0.1

library function MyFunction($value as real) as real
    return $value / 3.0
end

Function/Property/Enum/Struct Metadata Comments

Use metadata comments to supply information about functions, properties, enums, or structs that you declare in your AeroScript programs or libraries.

Function Metadata Comments

Automation1 Studio uses a set of attributes for function metadata comments to show autocomplete information in the Programming module.

The code sample that follows shows a metadata comment for a function, with attributes that you can use in Automation1 Studio.

/*!
    @summary Adds two values.
    @argument $a The first value to add.
    @argument $b The second value to add.
    @return The sum of $a and $b.
*/
library function Add($a as real, $b as real) as real
    return $a + $b
end

A metadata comment for a function can contain the attributes that follow:

• @summary - Tells you about the function.
• @argument - Specify this attribute only if the function has one or more arguments. This attribute tells you about the argument that is specified for the function. The @argument attribute is immediately followed by the name of the argument. The name of the argument is followed by text that tells you about it. You must include the specified function argument in the function definition. Specify each argument only one time.
• @return - Specify this attribute only if the function returns a value. This attribute tells you about the value that the function returns.

You can create other attributes, such as @myAttribute, that are specific to your project. But Automation1 Studio will not use them.

Property Metadata Comments

The code sample that follows shows a metadata comment for a property, with attributes that you can use in Automation1 Studio:

/*!
    @summary Sets or gets the value of I/O that controls a valve.
    @argument $index The index of the valve to control.
    @return The current state of the specified valve output.
*/
library property $valveOutput[$index as integer] as integer
    set
        DigitalOutputSet(X, $index, value)
    end

    get
        return DigitalOutputGet(X, $index)
    end
end

A metadata comment for a property can contain the attributes that follow:

• @summary - Tells you about the property.
• @argument - Specify this attribute only if the property has one or more indices. This attribute tells you about the specified property index. The @argument attribute is immediately followed by the name of the property index. The name of the property index is followed by text that tells you about it. You must include the specified property index in the property definition. Specify each property index only one time.
• @return - Specify this attribute only if the property has a get accessor. This attribute tells you about the value that the property returns.

You can create other attributes, such as @myAttribute, that are specific to your project. But Automation1 Studio will not use them.

Enum Metadata Comments

The code sample that follows shows metadata comments for an enum, with attributes that you can use in Automation1 Studio:

/*! @summary Specifies different colors. */
enum Color
    /*! @summary The color red. */
    Red
    /*! @summary The color green. */
    Green
    /*! @summary The color blue. */
    Blue
end

A metadata comment for an enum or an enum enumerator can contain the attributes that follow:

• @summary - Tells you about the enum or enumerator.

You can create other attributes, such as @myAttribute, that are specific to your project. But Automation1 Studio will not use them.

Struct Metadata Comments

The code sample that follows shows metadata comments for a struct, with attributes that you can use in Automation1 Studio:

/*! @summary Contains information for a 2D point. */
struct Point
    /*! @summary The X coordinate. */
    $x as real
    /*! @summary The Y coordinate. */
    $y as real
end

A metadata comment for a struct or struct member can contain the attributes that follow:

• @summary - Tells you about the struct or struct member.

You can create other attributes, such as @myAttribute, that are specific to your project. But Automation1 Studio will not use them.

Next Topic: Preprocessor