Appendix A. Style Guide Highlights

//! Demonstrates naming and documentation conventions for a small diagnostic helper.
const std = @import("std");

/// Represents a labelled temperature reading captured during diagnostics.
pub const TemperatureReading = struct {
    label: []const u8,
    value_celsius: f32,

    /// Writes the reading to the provided writer using canonical casing and units.
    pub fn format(self: TemperatureReading, writer: anytype) !void {
        try writer.print("{s}: {d:.1}°C", .{ self.label, self.value_celsius });
    }
};

/// Creates a reading with the given label and temperature value in Celsius.
pub fn createReading(label: []const u8, value_celsius: f32) TemperatureReading {
    return .{
        .label = label,
        .value_celsius = value_celsius,
    };
}

test "temperature readings print with consistent label casing" {
    const reading = createReading("CPU", 72.25);
    var backing: [64]u8 = undefined;
    var stream = std.io.fixedBufferStream(&backing);

    try reading.format(stream.writer());
    const rendered = stream.getWritten();

    try std.testing.expectEqualStrings("CPU: 72.3°C", rendered);
}

//! Keeps error vocabulary tight for a numeric parser so callers can react precisely.
const std = @import("std");

/// Enumerates the failure modes that the parser can surface to its callers.
pub const ParseCountError = error{
    EmptyInput,
    InvalidDigit,
    Overflow,
};

/// Parses a decimal counter while preserving descriptive error information.
pub fn parseCount(input: []const u8) ParseCountError!u32 {
    if (input.len == 0) return ParseCountError.EmptyInput;

    var acc: u64 = 0;
    for (input) |char| {
        if (char < '0' or char > '9') return ParseCountError.InvalidDigit;
        const digit: u64 = @intCast(char - '0');
        acc = acc * 10 + digit;
        if (acc > std.math.maxInt(u32)) return ParseCountError.Overflow;
    }

    return @intCast(acc);
}

test "parseCount reports invalid digits precisely" {
    try std.testing.expectEqual(@as(u32, 42), try parseCount("42"));
    try std.testing.expectError(ParseCountError.InvalidDigit, parseCount("4a"));
    try std.testing.expectError(ParseCountError.EmptyInput, parseCount(""));
    try std.testing.expectError(ParseCountError.Overflow, parseCount("42949672960"));
}

//! Highlights a layered module layout with focused helper functions and tests.
const std = @import("std");

/// Errors that can emerge while normalizing user-provided retry policies.
pub const RetryPolicyError = error{
    ZeroAttempts,
    ExcessiveDelay,
};

/// Encapsulates retry behaviour for a network client, including sensible defaults.
pub const RetryPolicy = struct {
    max_attempts: u8 = 3,
    delay_ms: u32 = 100,

    /// Indicates whether exponential backoff is active.
    pub fn isBackoffEnabled(self: RetryPolicy) bool {
        return self.delay_ms > 0 and self.max_attempts > 1;
    }
};

/// Partial options provided by configuration files or CLI flags.
pub const PartialRetryOptions = struct {
    max_attempts: ?u8 = null,
    delay_ms: ?u32 = null,
};

/// Builds a retry policy from optional overrides while keeping default reasoning centralized.
pub fn makeRetryPolicy(options: PartialRetryOptions) RetryPolicy {
    return RetryPolicy{
        .max_attempts = options.max_attempts orelse 3,
        .delay_ms = options.delay_ms orelse 100,
    };
}

fn validate(policy: RetryPolicy) RetryPolicyError!RetryPolicy {
    if (policy.max_attempts == 0) return RetryPolicyError.ZeroAttempts;
    if (policy.delay_ms > 60_000) return RetryPolicyError.ExcessiveDelay;
    return policy;
}

/// Produces a validated policy, emphasising the flow from raw input to constrained output.
pub fn finalizeRetryPolicy(options: PartialRetryOptions) RetryPolicyError!RetryPolicy {
    const policy = makeRetryPolicy(options);
    return validate(policy);
}

test "finalize rejects zero attempts" {
    try std.testing.expectError(
        RetryPolicyError.ZeroAttempts,
        finalizeRetryPolicy(.{ .max_attempts = 0 }),
    );
}

test "finalize accepts defaults" {
    const policy = try finalizeRetryPolicy(.{});
    try std.testing.expectEqual(@as(u8, 3), policy.max_attempts);
    try std.testing.expect(policy.isBackoffEnabled());
}