Comments and documentation

OSTW has 3 types of comments: line comments, block comments, and doc/action comments.

• Line comments: // text
• Block comments: /* text */
• Doc/action comments: # text

Table of contents

• Action comments
• Doc comments

Action comments

Statements which generate actions can be preceded by a # comment to generate a workshop comment.

Example:

💠 OSTW code

# Notify players that the game has begun.
# Also display the number of goals remaining.
SmallMessage(AllPlayers(), $'The game has begun! Goal remaining: {goals_remaining}');

🔧 Workshop code

actions {
    "Notify players that the game has begun.
Also display the number of goals remaining."
    Small Message(All Players(All Teams), Custom String('The game has begun! Goals remaining: {0}', Global.goals_remaining));
}

Doc comments

Definitions can be documented by preceding them with # comments. Definition documentation will be shown in the IDE when hovering over definitions or when using the autocomplete. Markdown syntax is supported.

Code blocks inside doc comments will have their syntax highlighted in the text document. Code blocks without a language specified will be ostw by default. The overpy and workshop syntaxes are also supported, and can be marked by adding the name of the language after the ```.

Parameters in functions can be documented by writing # - `parameter_name`: text. The documentation will be displayed in the signature info window.

Notice: as of writing enums & enum values can't be documented, but everything else can.

Example

# Pairs a list of keys and values.
# 
# Values can be linked to keys which can be accessed later via those same keys.
# ```
# define myTable = Table<Number, String>.newTable([1, 2, 3], ['one', 'two', 'three']);
# ```
# 🔧 *This will compile as:*
# ```workshop
# Global.myTable_Keys = Array(1, 2, 3);
# Global.myTable_Values = Array(Custom String("One"), Custom String("Two"), Custom String("Three"));
# ```
# 
# ---
# These code samples in the ***Ostw***, ***Overpy***, and ***Workshop*** languages are equivalent and
# will all do the same thing.
# ```
# //💠 ostw
# String result = Table<Number, String>.newTable([1, 2, 3], ['one', 'two', 'three']).get(2);
# ```
# ```overpy
# #🐍 Overpy (slight difference: will return first element if no value matches)
# result = { 1: "one", 2: "two", 3: "three" }[2]
# ```
# ```workshop
# "🔧 Workshop"
# Global.result = Array(Custom String("one"), Custom String("two"), Custom String("three"))
#   [Index Of Array Value(Array(1, 2, 3), 2)];
# ```
struct Table<K, V>
{
    public K[] Keys;
    public V[] Values;

    # Obtains a value based on its respective key.
    public V get(in K key) {
        return Values[Keys.IndexOf(key)];
    }

    # Converts a table from `Table<K, V>` to `Table<K, OV>`.
    # 
    # ---
    # While this can be used to actually map the value, it can also be used to adhere to
    # OSTW's semantics. This meaning depending on usage an actual expensive `Mapped Array`
    # may not be compiled. For example:
    # ```
    # struct Node { public Number Distance; public Number Parent; }
    # define nodeTable = Table<Number, Node>.newTable();
    # ```
    # 🔧 *This will compile as:*
    # ```workshop
    # Global.nodeTable_Keys = ...;
    # Global.nodeTable_Values_Distance = ...;
    # Global.nodeTable_Values_Parent = ...;
    # ```
    # If the `Distance` value is no longer of use to the logic and can be discarded,
    # `mapValue` can be used to select the `Parent` values.
    # ```
    # define parentTable = nodeTable.mapValue<Number>(node => node.Parent);
    # ```
    # 🔧 *This will compile as:*
    # ```workshop
    # Global.parentTable_Keys = Global.nodeTable_Keys;
    # Global.parentTable_Values = Global.nodeTable_Values_Parent;
    # ```
    # - `map`: The lambda expression that will convert `V` to `OV`.
    public Table<K, OV> mapValue<OV>(const V => OV map) {
        return {
            Keys: Keys,
            Values: Values.Map(v => map(v))
        };
    }

    # Creates a new table with the specified keys and values.
    # - `keys`: The accessing keys that can be linked to a value. Should be the same length as `values`.
    # - `values`: Each key's value. Should be the same length as `keys`. The zeroth value links to
    # the zeroth value in the keys array and so on.
    public static Table<K, V> newTable(in K[] keys = [], in V[] values = []) {
        return {
            Keys: keys,
            Values: values
        };
    }
}

The documentation will look like this in vscode: