Developer documentation restored.

For those unaware, prior to this week, the documentation at https://developer.wordpress.org/reference hadn’t been updated since WordPress 6.4 — over two years out of date! Today, thankfully, this post is announcing that the reference documentation is now updated as of WordPress 6.9.1.

WordPress has seen significant change since the documentation generation process stopped, so if you found that something was missing then it wasn’t just you. Those new interfaces, classes, methods, functions, and hooksHooks In WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. should be there now. Further, there was a pre-existing bugbug A bug is an error or unexpected result. Performance improvements, code optimization, and are considered enhancements, not defects. After feature freeze, only bugs are dealt with, with regressions (adverse changes from the previous version) being the highest priority. where source snippets for many symbols were offset; this has been fixed in Monday’s update.

This work was the result of collaboration between many people, most of whom have never worked with this process in the past. @dd32, @dmsnell, @johnbillion, @jonsurrell, and @tmdk all worked on various approaches to restoring the ability to parse WordPress’ source code; and @dd32 and @coffee2code made sure that the updates reached the public website; and of course, numerous people in the #docs team reported and triaged bug reports that were symptoms of this process breakdown.

There is still significant work to do, as there is no way (at the time of writing this note) to generate the documentation for the upcoming WordPress 7.0 release, but as the new issues are ironed out, you can expect the updates to come much sooner than 2028 😉

There still remain a number of known issues, particularly related to PHPStan type annotations. Work is ongoing to improve the overall build process and try to reduce the feedback loopLoop The Loop is PHP code used by WordPress to display posts. Using The Loop, WordPress processes each post to be displayed on the current page, and formats it according to how it matches specified criteria within The Loop tags. Any HTML or PHP code in the Loop will be processed on each post. https://codex.wordpress.org/The_Loop. between making code changes and seeing those reflected in the documentation online.

Timeline

• August 1, 2023 — [56345] introduces a code-styling change to replace array_key_exists() with isset() while indexing a class constant. This was known to be unsupported by the docs parser but there was no indication that the updating process was broken. Because of a parsing error the process was blocked; the documentation generator needed to update its underlying dependency on nikic/php-parser so that it could understand the new syntax in the underlying source code.
• April 15, 2024 — [58009] introduces type annotations for optional types, ?array instead of array, which the updated parser could parse, but which phpDocumentor/Reflection did not recognize. The Reflection library extracts useful information from the parsed form of the source code, but had no code path for nullable types. Once the new syntax appeared in the source code, it needed to be updated to add the missing handling.
• June 3, 2024 — [58304] introduces a shorthand syntax for calling a Callable stored in a variable. This should be supported by the PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 7.4 or higher parser and Reflection, but it isn’t. It would need an update at least to the Reflection library to handle. Given that it is an odd construct with a semantically-equivalent counterpart, it was modified in [61624] to prevent it from becoming an immediate issue going forward.
• August 27, 2025 — [60684] introduces anonymous classes, which leads to a crash when Reflection tries to extract its name. There is no name, so it must make one up: class@anonymous.

There have only been four kinds of new syntax that broke the documentation generation since WordPress 6.4, but the code in WordPress 7.0 introduces several new syntax forms which need updating before the documentation can be regenerated:

• The AI client introduces visibility on class constants and nullable types for class properties.
• The collaboration feature introduce array initialization of class properties.

Work has already been explored for making another incremental step to update the underlying PHP parser, and this should hopefully resolve these new breakages.

The underlying PHP parser is somewhat comprehensive, but the adapter layer is more as-needed. When syntax forms aren’t present in the WordPress codebase there’s no need for them to exist in the documentation generator. Typically, when these new forms appear it shouldn’t take too much effort to update the adapter to add support for them. It can be harder though when updating PHP versions introduces new deprecations and when dependency updates involve backwards-incompatible changes. For example, updating to the next version of the phpDocumentor/Reflections library would require an almost complete rewrite of the adapter layer.

• July 13, 2025 — Work starts in PR#247 to rewrite the documentation generation with a new parser, a new adapter, and a new runner. This work incorporates PHPStan so that the more advanced types appear in the documentation.
• September 28, 2025 — An attempt is made in PR#248 to filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. out unsupported syntax using PCRE patterns.
• February 11, 2026 — Minimal updates are proposed in PR#250 (and in PR#249 and PR#251) to update the underlying nikic/php-parser dependency and liberate the process. The Reflection library is forked from its older version to adopt only those changes necessary to upgrade far enough to support CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.’s code (in PR#721).
• February 17–19, 2026 — The JSONJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. blob which represents the content of the documentation is generated from 6.9.1 and differences from the latest-working version are ironed out.
• February 23, 2026 — https://developer.wordpress.org/reference is updated with documentation for WordPress as of 6.9.1.

Future direction

What comes next is making sure that WordPress 7.0 can ship with updated reference documentation. That’s essential.

After that, work will continue on supporting PHPStan type annotations and on being able to generate documentation previews. The existing process is tightly coupled to the production system which hosts the documentation. It needs to be isolated into a Playground blueprint, at which point a preview can be generated on every PR and developers will be able to see the impact of changes before the WordPress release, and hopefully notice and fix any issues that arise before they are published publicly.

The process for generating and deployingDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. documentation updates is in dire need of its own documentation. A challenge in this current crisis has been knowing where to run updates and what updates to run. It’s one thing to parse the source code and produce the raw content, but another thing to have access to and awareness of the public servers.

A contributing factor to this breakdown was a failure to notify developers when source code changes broke the documentation generation process. A new CI job to run the parser could highlight these issues and raise awareness before problems escalate or cascade. That hopefully will not involve too much work, but needs to be undertaken by someone willing to push through the changes.

Finally, there is a backlog of feature requests for the documentation: new alerts, supporting pass-by-reference parameters, improving recognition of rarer code patterns, etc… Once the process is running smoothly and developers are able to recreate the system locally, the normal develop cycle should resume.

Props

Thanks to @jonsurrell for reviewing this post prior to publishing.

#developer-documentation