onyx-lang / onyx

✨ The compiler and developer toolchain for Onyx
https://onyxlang.io
BSD 2-Clause "Simplified" License
576 stars 22 forks source link

[Feature Request] Doc comments inside enums and structs #163

Closed clsource closed 14 hours ago

clsource commented 3 days ago

The compiler will not allow doc comments inside enum or struct members.

Failed to compile your code:

Line 21, column 8:
    expected token 'a symbol', got 'a doc comment'.
 21 |     /// The name of the sloth.
/// A model representing a sloth.
///
/// Sloths are mammals known for their slowness of movement. They spend most of their lives hanging upside down in trees.
///
/// You can create a sloth using the ``init_sloth/3`` initializer, or
/// create a randomly generated sloth using ``Generators/generate_sloth/1``:
///
/// ```onyx
/// habitat := Sloth.init_habitat(is_humid = true, is_warm = true)
///
/// sloth := Generators.generate_sloth(habitat)
/// ```
Sloth :: struct {
    /// The name of the sloth.
    name: str;
}

Currently I am documenting like this

/*
Abstract:
The model type for the color of a sloth.
*/
package Sloth

/// The color of a sloth.
/// - Members:
///     - Green: The color green.
///     - Yellow: The color yellow.
///     - Orange: The color orange.
///     - Blue: The color blue.
Color :: enum {
    Green;
    Yellow;
    Orange;
    Blue;
}

This would be the ideal

/// The color of a sloth.
Color :: enum {
    /// The color green.
    Green;

    /// The color yellow.
    Yellow;

    /// The color orange.
    Orange;

    /// The color blue.
    Blue;
}

Example

/// - Members:
///     - name: The name of the food.
///     - energy: The amount of energy the food contains.
///     When sloths metabolize the food they eat, their `Sloth/energy_level`
///     increases by the amount of energy the food contains.
Food :: struct {
    name: str;
    energy: i32;
}

This is the ideal

/// Sloth Food
Food :: struct {
    /// The name of the food.
    name: str;
    /// The amount of energy the food contains.
    /// When sloths metabolize the food they eat, their `Sloth/energy_level`
    /// increases by the amount of energy the food contains.
    energy: i32;
}