Doc Tags

@param/@returns/@throws on safe_add and lookup; @example on power; @see on a pair of temperature conversions; @since/@deprecated on add/old_add; all tags combined on linear_search.

// ============================================================

// Doc Tags in Zolo

// ============================================================

// Doc comments support special tags that are formatted as rich

// markdown in the editor's hover.

//

// Supported tags:

//   @param name description  - documents a parameter

//   @returns description     - documents the return value

//   @throws description      - documents possible errors

//   @example                 - usage example block

//   @see symbol              - cross-reference

//   @since version           - version it was added in

//   @deprecated reason       - marks as obsolete


// -- @param and @returns --------------------------------------


/// Adds two values safely, returning 0 if both are negative.

/// @param a First number

/// @param b Second number

/// @returns The sum of a and b, or 0 if both are negative

fn safe_add(a: int, b: int) -> int {
    if a < 0 && b < 0 { return 0 }
    return a + b
}

print("safe_add(10, 3) = {safe_add(10, 3)}")
print("safe_add(-1, -2) = {safe_add(-1, -2)}")

// -- @throws --------------------------------------------------


/// Looks up an element by index in the array.

/// @param arr The array to search

/// @param index The desired position (0-based)

/// @returns The element at the given position, or -1 if invalid

/// @throws Returns -1 for out-of-bounds indices

fn lookup(arr: [int], index: int) -> int {
    if index < 0 { return -1 }
    return arr[index]
}

let nums = [10, 20, 30]
print("nums[1] = {lookup(nums, 1)}")

// -- @example -------------------------------------------------


/// Computes the power of a number.

/// @param base The base number

/// @param exp The exponent (must be >= 0)

/// @returns base raised to exp

/// @example

/// let result = power(2, 10)

/// print(result)  // 1024

fn power(base: int, exp: int) -> int {
    var result = 1
    for i in 0..exp {
        result = result * base
    }
    return result
}

print("2^10 = {power(2, 10)}")

// -- @see -----------------------------------------------------


/// Converts degrees Celsius to Fahrenheit.

/// @param celsius Temperature in degrees Celsius

/// @returns Temperature in degrees Fahrenheit

/// @see fahrenheit_to_celsius

fn celsius_to_fahrenheit(celsius: float) -> float {
    return celsius * 1.8 + 32.0
}

/// Converts degrees Fahrenheit to Celsius.

/// @param fahrenheit Temperature in degrees Fahrenheit

/// @returns Temperature in degrees Celsius

/// @see celsius_to_fahrenheit

fn fahrenheit_to_celsius(fahrenheit: float) -> float {
    return (fahrenheit - 32.0) / 1.8
}

print("100C = {celsius_to_fahrenheit(100.0)}F")
print("212F = {fahrenheit_to_celsius(212.0)}C")

// -- @since and @deprecated -----------------------------------


/// Adds two numbers.

/// @param a First number

/// @param b Second number

/// @returns The sum of a and b

/// @since 0.1.0

fn add(a: int, b: int) -> int {
    return a + b
}

/// Adds two numbers (legacy version).

/// @deprecated Use add() instead

fn old_add(a: int, b: int) -> int {
    return a + b
}

print("3 + 4 = {add(3, 4)}")

// -- Combining all tags ---------------------------------------


/// Linear search in an array.

///

/// Walks the array from start to end looking for the target value.

/// Returns the index of the first occurrence or -1 if not found.

///

/// @param arr Array of integers to search

/// @param target Value to find

/// @returns Index of the element, or -1 if not found

/// @since 0.2.0

/// @example

/// let pos = linear_search([10, 20, 30], 20)

/// print(pos)  // 1

fn linear_search(arr: [int], target: int) -> int {
    for i in 0..5 {
        if arr[i] == target {
            return i
        }
    }
    return -1
}

let data = [5, 10, 15, 20, 25]
print("Position of 15: {linear_search(data, 15)}")
print("Position of 99: {linear_search(data, 99)}")