generate-docs.php

<?php

/**
 * A script to generate stubs for IDE autocompletion and Markdown docs
 * for the 'oqs' extension.
 *
 * Usage:
 *   php generate-docs.php --format=stub > oqs.stub.php
 *   php generate-docs.php --format=markdown > OQS_CONSTANTS.md
 */

if (!extension_loaded('oqs')) {
    fwrite(STDERR, "Error: The 'oqs' extension must be loaded to run this script.\n");
    exit(1);
}

$options = getopt('', ['format:']);
$format = $options['format'] ?? 'stub'; // Default to stub

if (!in_array($format, ['stub', 'markdown'])) {
    fwrite(STDERR, "Error: Invalid format '{$format}'. Use 'stub' or 'markdown'.\n");
    exit(1);
}

// -----------------------------------------------------------------------------
//  Helper Functions
// -----------------------------------------------------------------------------

function format_type(?ReflectionType $type): string
{
    if (!$type) {
        return '';
    }
    if ($type instanceof ReflectionNamedType) {
        return ($type->allowsNull() && $type->getName() !== 'mixed' ? '?' : '') . $type->getName();
    }
    if ($type instanceof ReflectionUnionType) {
        $parts = array_map(fn ($t) => $t->getName(), $type->getTypes());
        return ($type->allowsNull() ? '?' : '') . implode('|', $parts);
    }
    return 'mixed';
}

function format_value($value): string
{
    if (is_null($value)) {
        return 'null';
    }
    if (is_string($value)) {
        return "'" . addslashes($value) . "'";
    }
    if (is_bool($value)) {
        return $value ? 'true' : 'false';
    }
    return (string)$value;
}

// -----------------------------------------------------------------------------
//  Data Generation using Reflection
// -----------------------------------------------------------------------------

function get_class_info(string $className): array
{
    $class = new ReflectionClass($className);
    $constants = $class->getConstants();
    ksort($constants);

    $methods = [];
    foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
        if ($method->getDeclaringClass()->getName() !== $className) {
            continue;
        }
        $params = [];
        foreach ($method->getParameters() as $param) {
            $params[] = [
                'name' => $param->getName(),
                'type' => format_type($param->getType()),
                'has_default' => $param->isDefaultValueAvailable(),
                'default_value' => $param->isDefaultValueAvailable() ? $param->getDefaultValue() : null,
            ];
        }
        $methods[] = [
            'name' => $method->getName(),
            'is_static' => $method->isStatic(),
            'return_type' => format_type($method->getReturnType()),
            'params' => $params,
        ];
    }
    return [
        'name' => $className,
        'constants' => $constants,
        'methods' => $methods
    ];
}

$classes = [
    get_class_info(Oqs\Kem::class),
    get_class_info(Oqs\Sig::class),
];

$all_constants = get_defined_constants(true);
$oqs_extension_constants = $all_constants['oqs'] ?? [];

$global_oqs_constants = [];
foreach ($oqs_extension_constants as $name => $value) {
    if (str_starts_with($name, 'OQS\\')) {
        $shortName = substr($name, strlen('OQS\\'));
        $global_oqs_constants[$shortName] = $value;
    }
}
ksort($global_oqs_constants);

// -----------------------------------------------------------------------------
//  Output Generation
// -----------------------------------------------------------------------------

if ($format === 'stub') {
    echo "<?php\n\n";
    echo "// @generated by generate-docs.php. Do not edit.\n";
    echo "// This file is for IDE autocompletion.\n\n";
    echo "namespace Oqs;\n\n";

    if (!empty($global_oqs_constants)) {
        echo "// --- Global Constants ---\n";
        foreach ($global_oqs_constants as $name => $value) {
            $type = gettype($value);
            echo "/** @var {$type} Version information from the underlying liboqs library. */\n";
            echo "const {$name} = " . format_value($value) . ";\n\n";
        }
    }

    echo "class Exception extends \Exception {}\n\n";

    foreach ($classes as $classInfo) {
        $shortName = (new ReflectionClass($classInfo['name']))->getShortName();
        echo "final class {$shortName}\n{\n";

        if (!empty($classInfo['constants'])) {
            foreach ($classInfo['constants'] as $name => $value) {
                echo "    /** @var string The \"{$value}\" algorithm. */\n";
                echo "    public const {$name} = '{$value}';\n\n";
            }
        }

        foreach ($classInfo['methods'] as $method) {
            $param_docs = [];
            $param_signatures = [];
            foreach ($method['params'] as $param) {
                $param_docs[] = "     * @param " . ($param['type'] ? $param['type'] . ' ' : '') . '$' . $param['name'];
                $sig_part = ($param['type'] ? $param['type'] . ' ' : '') . '$' . $param['name'];
                if ($param['has_default']) {
                    $sig_part .= ' = ' . format_value($param['default_value']);
                }
                $param_signatures[] = $sig_part;
            }
            echo "    /**\n";
            foreach ($param_docs as $doc) {
                echo $doc . "\n";
            }
            if ($method['return_type']) {
                echo "     * @return " . $method['return_type'] . "\n";
            }
            echo "     */\n";
            $static_kw = $method['is_static'] ? 'static ' : '';
            $return_kw = $method['return_type'] ? ': ' . $method['return_type'] : '';
            $param_str = implode(', ', $param_signatures);
            echo "    public {$static_kw}function {$method['name']}({$param_str}){$return_kw} {}\n\n";
        }
        echo "}\n";
    }

} elseif ($format === 'markdown') {

    if (!empty($global_oqs_constants)) {
        echo "### Global Constants\n\n";
        echo "These constants provide version information for the underlying `liboqs` C library that the extension was compiled against.\n\n";
        echo "| Constant Name | Value |\n";
        echo "|---------------|-------|\n";
        foreach ($global_oqs_constants as $name => $value) {
            // Display the fully qualified constant name for clarity in docs
            echo "| `Oqs\\{$name}` | `{$value}` |\n";
        }
        echo "\n";
    }

    foreach ($classes as $classInfo) {
        $shortName = (new ReflectionClass($classInfo['name']))->getShortName();
        echo "### `Oqs\\{$shortName}` Constants\n\n";
        echo "| Constant Name | Algorithm Value |\n";
        echo "|---------------|-----------------|\n";
        foreach ($classInfo['constants'] as $name => $value) {
            echo "| `{$name}` | `{$value}` |\n";
        }
        echo "\n";
    }
}