Documentation Tools

Document your Strada code with POD and generate HTML documentation.

Overview

Strada supports POD (Plain Old Documentation), the same documentation format used by Perl. POD allows you to embed documentation directly in your source files, which can then be converted to HTML, man pages, or other formats.

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 extracts POD from Strada source files and generates HTML documentation.

Basic Usage

# Generate HTML for a single file
./tools/stradadoc lib/JSON.strada > JSON.html

# Generate documentation for all libraries
for f in lib/*.strada; do
    ./tools/stradadoc "$f" > "docs/$(basename "$f" .strada).html"
done

Output Features

• Syntax-highlighted code blocks
• Styled headings and lists
• Responsive design
• Table of contents from headings

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 to view them:

# View JSON library documentation
./tools/stradadoc lib/JSON.strada | less

# Generate HTML docs for all libraries
mkdir -p website/docs/lib
for f in lib/*.strada lib/*/*.strada; do
    name=$(basename "$f" .strada)
    ./tools/stradadoc "$f" > "website/docs/lib/$name.html"
done

Available Libraries