Documentation Tools

Document your Strada code with POD and read it in the terminal with stradadoc.

Overview

Strada supports POD (Plain Old Documentation), the same documentation format used by Perl. POD lets you embed documentation directly in your source files. The stradadoc tool renders POD and markdown documentation to the terminal (perldoc-style); for HTML or man-page output, use strada-md2html or strada-md2man.

POD Basics

POD blocks start with a directive (like =head1) and end with =cut. The compiler automatically skips POD blocks, so they don't affect compilation.

Basic Structure

=head1 NAME

MyLib - A brief description of my library

=head1 SYNOPSIS

    use lib "lib";
    use MyLib;

    my int $result = MyLib::add(10, 20);

=head1 DESCRIPTION

MyLib provides utility functions for mathematical operations.

=head1 FUNCTIONS

=head2 add($a, $b)

Returns the sum of two integers.

=head2 multiply($a, $b)

Returns the product of two integers.

=cut

package MyLib;

func add(int $a, int $b) int {
    return $a + $b;
}

POD Directives

Inline Formatting

Code Blocks

Indent text by 4 spaces to create a code block:

=head1 EXAMPLE

    # This is a code block
    my int $x = 10;
    say($x);

=cut

Lists

Create bullet lists with =over, =item, and =back:

=head1 FEATURES

=over 4

=item * Fast compilation

=item * Native executables

=item * Perl-like syntax

=back

Standard Sections

By convention, POD documentation includes these sections:

stradadoc Tool

The stradadoc tool renders a documentation topic or module to the terminal, perldoc-style. It takes a topic/module name (not a file path) and formats the matching POD/markdown with ANSI colors, paging through less.

Basic Usage

# List all available documentation
./tools/stradadoc

# Show a topic or module
./tools/stradadoc sys                  # core:: functions
./tools/stradadoc LANGUAGE             # the language guide
./tools/stradadoc Device::SerialPort   # a module's docs

Options

• --list, -l — list all available documentation
• --raw — show raw POD/markdown without formatting
• --no-pager — don't page through less
• --help, -h — show help

For HTML or man-page output, use strada-md2html or strada-md2man instead.

Complete Example

Here's a fully documented library following best practices:

=head1 NAME

List::Util - Common list utility functions for Strada

=head1 SYNOPSIS

    use lib "lib";
    use List::Util;

    my array @nums = (3, 1, 4, 1, 5, 9);
    my int $max = List::Util::max(@nums);       # 9
    my int $sum = List::Util::sum(@nums);       # 23
    my int $first = List::Util::first(@nums);   # 3

=head1 DESCRIPTION

List::Util provides commonly needed list processing functions.
All functions operate on arrays and return scalar values.

=head1 FUNCTIONS

=head2 sum(@array)

Returns the sum of all elements in the array.

    my int $total = List::Util::sum(@prices);

=head2 max(@array)

Returns the maximum value in the array.

    my int $highest = List::Util::max(@scores);

=head2 min(@array)

Returns the minimum value in the array.

    my int $lowest = List::Util::min(@scores);

=head2 first(@array)

Returns the first element of the array (same as C<@array[0]>).

=head1 SEE ALSO

L, L

=cut

package List::Util;

func sum(array @arr) int {
    my int $total = 0;
    foreach my int $n (@arr) {
        $total = $total + $n;
    }
    return $total;
}

func max(array @arr) int {
    my int $max = @arr[0];
    foreach my int $n (@arr) {
        if ($n > $max) {
            $max = $n;
        }
    }
    return $max;
}

func min(array @arr) int {
    my int $min = @arr[0];
    foreach my int $n (@arr) {
        if ($n < $min) {
            $min = $n;
        }
    }
    return $min;
}

func first(array @arr) scalar {
    return @arr[0];
}

Built-in Library Documentation

All standard library modules include POD documentation. Use stradadoc with the module name to view it:

# View a module's documentation (by name, not file path)
./tools/stradadoc JSON

# List everything stradadoc can show
./tools/stradadoc --list

# To produce HTML instead, use strada-md2html
./tools/strada-md2html docs/SOME_DOC.md > some_doc.html

Available Libraries