Introduction to Compiler Annotations in Pine Script

Compiler annotations in Pine Script™ play a crucial role in enhancing the script’s readability, documentation, and functionality. These annotations, essentially comments with special instructions for the compiler, allow developers to specify script settings, document functions, variables, and user-defined types (UDTs), and create more organized and understandable code. In this article, we’ll explore how compiler annotations can be utilized, focusing on an example script that draws a triangle on a trading chart using three interactively selected points.

Understanding Compiler Annotations

Pine Script™ Version

//@version= annotation specifies the Pine Script™ version for the compiler. It’s critical to match the script with the appropriate version for compatibility and access to the latest features.

Descriptions

//@description provides a custom description for scripts that implement the library() declaration, enhancing script documentation.
Annotations like //@function, //@param, and //@returns offer detailed descriptions for user-defined functions, their parameters, and return values, respectively.
For documenting UDTs and their fields, //@type and //@field annotations are used.

Utility Annotations

//@variable adds a custom description for variables, improving code clarity.
//@strategy_alert_message sets a default message for strategy scripts in the alert creation dialogue, streamlining the alert setup process.
//#region and //#endregion facilitate code organization by creating collapsible code regions within the Pine Editor, making large scripts easier to navigate.

Example: Drawing a Triangle

//@version=5
indicator("Interactive Triangle Drawer", shorttitle="Triangle Drawer", overlay=true)

// Default values for the interactive inputs
int   DEFAULT_TIME  = 0
float DEFAULT_PRICE = 0.0

// Interactive inputs for the triangle's vertices
x1Input = input.time(DEFAULT_TIME,   "Vertex 1 Time", inline = "vertex1", confirm = true)
y1Input = input.price(DEFAULT_PRICE, "Vertex 1 Price", inline = "vertex1", tooltip = "Select Vertex 1", confirm = true)
x2Input = input.time(DEFAULT_TIME,   "Vertex 2 Time", inline = "vertex2", confirm = true)
y2Input = input.price(DEFAULT_PRICE, "Vertex 2 Price", inline = "vertex2", tooltip = "Select Vertex 2", confirm = true)
x3Input = input.time(DEFAULT_TIME,   "Vertex 3 Time", inline = "vertex3", confirm = true)
y3Input = input.price(DEFAULT_PRICE, "Vertex 3 Price", inline = "vertex3", tooltip = "Select Vertex 3", confirm = true)

// Documentation annotations for the custom type and its fields
//@type            Represents the vertices and color for drawing a triangle.
//@field time1     The time coordinate of the first vertex.
//@field time2     The time coordinate of the second vertex.
//@field time3     The time coordinate of the third vertex.
//@field price1    The price coordinate of the first vertex.
//@field price2    The price coordinate of the second vertex.
//@field price3    The price coordinate of the third vertex.
//@field triColor  The color of the triangle's edges.
type TriangleType
    int   time1
    int   time2
    int   time3
    float price1
    float price2
    float price3
    color triColor

// Annotation for the drawing function
//@function Draws a triangle on the chart.
//@param t  (TriangleType) The triangle object with vertices and color.
//@returns  None. Draws directly on the chart.
drawTriangle(TriangleType t) =>
    line.new(t.time1, t.price1, t.time2, t.price2, xloc = xloc.bar_time, color = t.triColor, width = 2)
    line.new(t.time2, t.price2, t.time3, t.price3, xloc = xloc.bar_time, color = t.triColor, width = 2)
    line.new(t.time3, t.price3, t.time1, t.price1, xloc = xloc.bar_time, color = t.triColor, width = 2)

// Main execution block
if barstate.islastconfirmedhistory
    // Documentation for the triangle object variable
    //@variable Holds the triangle's vertices and color.
    triangleObject = TriangleType.new()

    // Assigning input values to the triangle object
    triangleObject.time1  := x1Input
    triangleObject.time2  := x2Input
    triangleObject.time3  := x3Input
    triangleObject.price1 := y1Input
    triangleObject.price2 := y2Input
    triangleObject.price3 := y3Input
    triangleObject.triColor := color.new(color.blue, 0)

    // Drawing the triangle
    drawTriangle(triangleObject)

Script Breakdown

Script Initialization

//@version=5
indicator("Interactive Triangle Drawer", shorttitle="Triangle Drawer", overlay=true)

//@version=5: This compiler annotation specifies that the script is written for Pine Script version 5, ensuring compatibility with the trading platform’s features and functionalities.
indicator(...): This function initializes the script as a chart overlay. It sets the script’s name to “Interactive Triangle Drawer” and a shorter title for display purposes. The overlay=true parameter ensures that the drawing appears directly on the chart.

Default Values and Interactive Inputs

int   DEFAULT_TIME  = 0
float DEFAULT_PRICE = 0.0

These lines define default values for the time (DEFAULT_TIME) and price (DEFAULT_PRICE) inputs of the triangle’s vertices. They are set to 0 and 0.0, respectively, as placeholders.

x1Input = input.time(DEFAULT_TIME, "Vertex 1 Time", inline = "vertex1", confirm = true)
y1Input = input.price(DEFAULT_PRICE, "Vertex 1 Price", inline = "vertex1", tooltip = "Select Vertex 1", confirm = true)
...

input.time and input.price functions collect user inputs for the time and price coordinates of the triangle’s vertices. Each input is labeled (e.g., “Vertex 1 Time”) and grouped inline for better UI organization. The confirm=true parameter enables confirmation dialogs for inputs, preventing accidental changes.

Custom Type Definition

type TriangleType
    int   time1
    int   time2
    int   time3
    float price1
    float price2
    float price3
    color triColor

The type keyword defines a custom type TriangleType, representing a triangle with time and price coordinates for three vertices and a color for the lines (triColor). Compiler annotations above this section document the purpose and content of each field within the custom type.

Drawing Function

drawTriangle(TriangleType t) =>
    line.new(t.time1, t.price1, t.time2, t.price2, xloc = xloc.bar_time, color = t.triColor, width = 2)
    ...

The drawTriangle function takes a TriangleType object as input and draws the triangle on the chart using line.new functions. Each line.new call draws one edge of the triangle, with parameters specifying the start and end points, line color, and line width.

Script Execution

if barstate.islastconfirmedhistory
    triangleObject = TriangleType.new()
    ...
    drawTriangle(triangleObject)

This conditional block ensures that the triangle is drawn only once, during the last confirmed historical bar. It initializes a TriangleType object, assigns input values to its fields, and calls drawTriangle to render the triangle on the chart.

Key Features and Takeaways

Compiler Annotations Enhance Code Documentation: Annotations make the script self-documenting, facilitating easier understanding and maintenance.
Custom Types and Functions: Defining UDTs and custom functions allows for cleaner, more modular code. Annotations add valuable context to these definitions.
Interactive Input Handling: The script showcases how to handle interactive inputs from users, enabling dynamic content creation on charts.
Visual Scripting Applications: This example demonstrates Pine Script’s capability for visual scripting, allowing traders and developers to create custom charting tools.

Compiler annotations in Pine Script™ are powerful tools for creating more readable, organized, and documented code. By leveraging these annotations, developers can build sophisticated trading scripts and indicators that are easier to understand, maintain, and share with the community.