docs: automate API.md generation from Judy.stub.php#64
Merged
Conversation
Enrich Judy.stub.php with PHPDoc descriptions (benefiting IDEs), add scripts/api-metadata.php for supplemental metadata (type groups, examples, compatibility matrix), and scripts/generate-api-docs.php to generate API.md from both sources with drift detection. CI step added to verify API.md stays in sync (PHP 8.4 only).
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request introduces a robust, automated system for generating and maintaining the Highlights
Changelog
Ignored Files
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces an automated API documentation generation process, which is a significant improvement for maintaining documentation consistency. The Judy.stub.php file has been enriched with comprehensive PHPDoc comments, and new scripts (api-metadata.php and generate-api-docs.php) are added to produce API.md. The drift detection mechanism is a valuable addition to prevent inconsistencies between the stub and metadata. The identified issues related to type hinting consistency and script robustness remain relevant and should be addressed.
Test Results
Benchmark Results
Run Status
Memory Efficiency (Linux, PHP 8.5)
API Speedups (Linux, PHP 8.5)Speedup = PHP time / Judy time. Bold = Judy faster.
Core Types (Linux, PHP 8.5)Speedup = PHP time / Judy time. Bold = Judy faster.
All types detailCore Types (Linux, PHP 8.5) — AllSpeedup = PHP time / Judy time. Bold = Judy faster.
Cross-version detail (Linux)Core Types — LinuxEach cell: Judy ms (speedup vs PHP array).
API — Linux
Cross-version detail (Windows)Core Types — WindowsEach cell: Judy ms (speedup vs PHP array).
API — Windows
Windows results (PHP 8.5)Memory Efficiency (Windows, PHP 8.5)
API Speedups (Windows, PHP 8.5)Speedup = PHP time / Judy time. Bold = Judy faster.
Core Types (Windows, PHP 8.5)Speedup = PHP time / Judy time. Bold = Judy faster.
All types detailCore Types (Windows, PHP 8.5) — AllSpeedup = PHP time / Judy time. Bold = Judy faster.
Release Comparison (2.3.0 → 2.4.0)
Summary: 5 faster,
Memory ComparisonMemory:
50 new benchmarks (not in baseline)
Full benchmark outputLinux — PHP 8.5Windows — PHP 8.5 |
- Add missing `mixed` type hint to judy_type() in Judy.stub.php (aligns stub signature with its @param mixed PHPDoc tag; regenerates API.md and Judy_arginfo.h accordingly) - Add mb_strlen() fallback in generate-api-docs.php via str_width() helper (gracefully handles environments where mbstring is not loaded)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Judy.stub.phpwith PHPDoc descriptions on all 46 methods and 2 global functions (benefits IDEs and serves as source of truth for API docs)scripts/api-metadata.php— supplemental metadata file with type groupings, examples, compatibility matrix, and behavioral notes that don't fit in PHPDocscripts/generate-api-docs.php— PHP generator script that producesAPI.mdfrom both sources, with drift detection between stub and metadata--checkmode, PHP 8.4 only) to verify API.md stays in sync with source filesDesign
Dual-source approach: Stub provides signatures + descriptions; PHP array metadata provides type groupings, examples, supported-type annotations, compatibility matrix, and behavioral notes.
Drift detection: Generator cross-checks stub methods vs metadata sections and constants vs type_groups. Fails with clear errors if out of sync.
Stub safety: Only prose text in PHPDoc (no
@param/@returnwith descriptions) to avoid breakinggen_stub.phparginfo generation.Test plan
php scripts/generate-api-docs.php --checkexits 0 (API.md matches generated output)Judy_arginfo.hchanges are functionally identical (only alias optimizations and hash line)