Documentation

// Ordinary comments, like this one, are for whoever reads the source. Documentation comments are
// for whoever uses the API: tools collect them and turn them into reference pages. There are two
// spellings, `///` on each line or one `/** ... */` block, and both attach to the declaration
// directly below them. A blank line in between detaches the comment.
//
// The first sentence is the summary, shown on its own in indexes, so it should stand alone. Tags
// come after the prose and give the generator structure to work with:
//
//     @param name ...      one named parameter
//     @returns ...         the result
//     @see ...             a related item or a web address
//     @deprecated ...      what to use instead
//
// `rux doc` writes the pages to `Bin/Docs/`, starting at `index.html`; `rux doc --open` opens them.
// Only `pub` items appear, because the pages describe what other packages can use.
//
// Tag names are exact. Write `@return` instead of `@returns`, and the program still compiles, but
// `rux lint` warns "unknown documentation tag '@return'" and `rux doc` refuses to generate the
// page until it is fixed. `rux lint` also warns about any `pub` item left without documentation.
import Io::PrintLine;

/// A rectangle measured in whole units.
pub struct Rectangle {
    /// The horizontal side.
    pub width: int;
    /// The vertical side.
    pub height: int;
}

extend Rectangle {
    /**
        The space the rectangle covers.
        @returns `width` times `height`
    */
    pub func Area(self: &Rectangle) -> int {
        return self.width * self.height;
    }

    /// Makes a copy with both sides multiplied. The original is left as it was.
    /// @param factor what each side is multiplied by
    /// @returns the scaled copy
    pub func Scaled(self: &Rectangle, factor: int) -> Rectangle {
        return Rectangle { width: self.width * factor, height: self.height * factor };
    }

    /// The space the rectangle covers, under its earlier name.
    /// @returns the same value as `Area`
    /// @deprecated call `Area`, whose name says what it measures
    /// @see `Rectangle::Area`
    pub func Size(self: &Rectangle) -> int {
        return self.Area();
    }
}

func Main() -> int {
    let tile = Rectangle { width: 3, height: 2 };
    let floor = tile.Scaled(4);
    PrintLine("tile  {} x {} covers {}", tile.width, tile.height, tile.Area());
    PrintLine("floor {} x {} covers {}", floor.width, floor.height, floor.Area());
    return 0;
}