Repository navigation
Improve support of Enums #180
Description
Activity
Better rendering
To explicitly spell that out: Currently the doc comments are confusingly placed below the respective case, which can lead to off-by-one errors for users reading the docs.
- Linking support in
<type>and<enumname>
<type>would be used in parameters or return types and<enumname>more or less everywhere elsewhere, right?- Linking support for cases in
<enumidentifier>and possibly<constant>
<enumidentifier>could probably be added relatively easily as long as we define xml IDs on the enum definition pages and use FQNs elsewhere. If nobody beats me to it, I'll take a look at this.- Support for search
I think searching for the enum names is already working. Or do you mean searching for the cases/
<enumidentifier>s?- Linking support in
- Linking support in
<type>and<enumname>
<type>would be used in parameters or return types and<enumname>more or less everywhere elsewhere, right?What I meant is that
<type>tags should be able to understand enumerations and be able to link to the correct page :)
See: https://www.php.net/manual/en/function.bcround.php for what I mean.- Linking support for cases in
<enumidentifier>and possibly<constant>
<enumidentifier>could probably be added relatively easily as long as we define xml IDs on the enum definition pages and use FQNs elsewhere. If nobody beats me to it, I'll take a look at this.- Support for search
I think searching for the enum names is already working. Or do you mean searching for the cases/
<enumidentifier>s?Oh I didn't check, but being able to search for cases would be nice yes.
Reacted by haszi- Linking support in
php/doc-en#4371 also appears to be a PHD issue, as the versions are in versions.xml:
Reacted by Gina Peter BanyardI was wondering if is possible to embed these version details as
<!--version from="" -->comments, inside each functionsynopisys/methodsynopsys, so detecting/debugging would be also simpler.One thing I plan to work on this year is to move all PhD stuff inside
configure.phpto aftermanual.xmlloading and validation is done, so the time to error is not impacted by processing PhD stuff, that is discarted anyways, if there is a loading or validation fail ofmanual.xml.Reacted by Gina Peter Banyard- added a commit that references this issue
on Jan 30, 2026 - added a commit that references this issue
on Feb 3, 2026 Uh, I don't like the fact that enums are the only class type where a freeword text (the
enumitemdescription) is mixed together with the enum signature itself on the synopsis page. The latter can be generated directly based on the stubs while the former one needs additional input. :( That's unprecedented.Would it be possible to use a dedicated section for the enum case descriptions instead of the
enumitemdescriptionitems, similarly to properties?Uh, I don't like the fact that enums are the only class type where a freeword text (the
enumitemdescription) is mixed together with the enum signature itself on the synopsis page. The latter can be generated directly based on the stubs while the former one needs additional input. :( That's unprecedented.Would it be possible to use a dedicated section for the enum case descriptions instead of the
enumitemdescriptionitems, similarly to properties?Frankly I quite dislike the XML duplication for properties & constants and would prefer that DocBook provides a
<fielddescription>tag so that everything would be nicely grouped together. So I'd rather not. But I don't see the problem of having the XML element causes?But I don't see the problem of having the XML element causes?
If we want them to be generatable by gen_stub (or any other tool), we need to add the text inside the
enumitemdescriptionelement to the stubs. For example:enum RoundingMode { /** * @description Round to the nearest integer. * If the decimal part is <literal>5</literal>, * round to the integer with the larger absolute value. */ case HalfAwayFromZero; ... }Note the
<literal>XML tag which must be present in the stub. This is suboptimal very much. If the text is displayed outside of the enumsynopsis then we can generate the signature of the enum directly from the stub without the need to add the text to the stub.I don't understand why we would need to add the XML to the stub? Just store it somewhere else? To me, the main problem seems to be that gen_stub expects to be able to override and write raw "text" rather than patch the text and or return an XML Node that gets pretty printed.
I also find gen_stub to be extremely convoluted and difficult to assess it works properly because we effectively bolted on documentation tooling onto something that wasn't designed for it. And I'd rather invest time in working on something that properly deals with XML, and delegate the output to libxml by setting
Dom\Document::formatOutput = true;.I know that ext/libxml defaults to 2 spaces, and I was talking with @ndossche last year on a way to be able to change this behaviour from userland (rather than me patching the indentation from 2 to 1 space), as that's really the main blocker on top of us wrapping the
<type>element in()text nodes which messes up the render. But that's already not good XML markup from a semantic PoV as this is a rendering issue that should be handled by PhD not something present in the doc XML.Just store it somewhere else?
Where? 🤔 It would only make sense to store them in the stubs, if we really have to store them somewhere. But even if we find a suitable place, it's not optimal that the constant descriptions are disconnected from the manual, so I think it's not a good direction to take.
To me, the main problem seems to be that gen_stub expects to be able to override and write raw "text" rather than patch the text and or return an XML Node that gets pretty printed.
The Predefined Constant pages are overwritten this way: only the type is changed, and the description is kept as-is. So it's possible to implement of course, but so far the completely overwriting the
methodsynopsisandclassynopsiselements worked really well, so I wouldn't expect it not to work forenumsynopsis.I also find gen_stub to be extremely convoluted and difficult to assess it works properly because we effectively bolted on documentation tooling onto something that wasn't designed for it.
Yes, it's convoluted for sure. But why I don't think it's worth to create a separate tool for the documentation is because there's also a significant amount of boilerplate code for parsing the stub files and storing all the metadata, and all these are already available in gen_stub.php, and duplicating this whole lot of code doesn't seem a good idea for me either. Maybe splitting gen_stub.php into files as one would with a library would help instead?
And finally, I have yet another problem with the current enum descriptions: longer or more complex descriptions would look awful. Currently, the inline formatting is fine, because we only have fairly simple enum case descriptions. But the current rendering prevents the usage of multi-line text (e.g. similarly to the description of Deprecated::$since). And I'm not sure additional formatting (links,
varnametags etc) would work properly, at least I couldn't make it work. I attached a screenshot where I tried to create a multi-line description. and I really didn't like the result.
Just store it somewhere else?
Where? 🤔 It would only make sense to store them in the stubs, if we really have to store them somewhere. But even if we find a suitable place, it's not optimal that the constant descriptions are disconnected from the manual, so I think it's not a good direction to take.
I still don't understand why you are talking about storing them on the stubs. I don't want manual documentation in php-src. Like if you want to attach it to some higher level metadata in gen_stub then fine, but it can just be an XML node, you don't need to write it as a doc comment.
To me, the main problem seems to be that gen_stub expects to be able to override and write raw "text" rather than patch the text and or return an XML Node that gets pretty printed.
The Predefined Constant pages are overwritten this way: only the type is changed, and the description is kept as-is. So it's possible to implement of course, but so far the completely overwriting the
methodsynopsisandclassynopsiselements worked really well, so I wouldn't expect it not to work forenumsynopsis.This only works when updating, trying to generate manual pages with gen_stub is always an uphill battle.
I also find gen_stub to be extremely convoluted and difficult to assess it works properly because we effectively bolted on documentation tooling onto something that wasn't designed for it.
Yes, it's convoluted for sure. But why I don't think it's worth to create a separate tool for the documentation is because there's also a significant amount of boilerplate code for parsing the stub files and storing all the metadata, and all these are already available in gen_stub.php, and duplicating this whole lot of code doesn't seem a good idea for me either. Maybe splitting gen_stub.php into files as one would with a library would help instead?
I don't parse the stub files manually, I use
BetterReflectionand this works very well.
And if there is any other parsing code that is necessary then I am happy to move the parsing code from gen_stub tostub-to-docbook.
The most tedious aspect is parsing XML, especially function pages that document multiple signatures/procedural and OO APIs. AFAIK gen_stub doesn't automatically update<parameter>names in various descriptions, nor does it update verxion.xml.But this ignores the biggest problem IMHO, the lack of testing.
And finally, I have yet another problem with the current enum descriptions: longer or more complex descriptions would look awful. Currently, the inline formatting is fine, because we only have fairly simple enum case descriptions. But the current rendering prevents the usage of multi-line text (e.g. similarly to the description of Deprecated::$since). And I'm not sure additional formatting (links,
varnametags etc) would work properly, at least I couldn't make it work. I attached a screenshot where I tried to create a multi-line description. and I really didn't like the result.
These are rendering issues. Not XML issues. The "inline" description was always a temporary measure. PhD has a really frustrating architecture in how it renders stuff and makes it annoying to be able to "move" tags around. Nothing in the XML Schema prevents the use of any such tags. Sadly I am not 4 people that can work on doc-en, PhD, php-src, and trying to fix translations so we can do bulk changes in doc-en more easily.
If you want to continue working on documentation support on gen_stub you can, but I am extremely reluctant to amend XML markup, deviating from a standard schema just to accommodate tooling. Tooling is meant to help us, not force us to do things in a way that makes it easy for the tooling to achieve it's goal.
I still don't understand why you are talking about storing them on the stubs. I don't want manual documentation in php-src.
Me neither, of course, that's why I brought up my problem.
This only works when updating, trying to generate manual pages with gen_stub is always an uphill battle.
I pretty much love what you implemented a few years ago: the class synopsis page skeleton is a perfect start, and it worked quite well for me in case of the ext/uri documentation. If we had the same for the method synopsis pages, then documentation generation would also be more convenient.
AFAIK gen_stub doesn't automatically update names in various descriptions, nor does it update verxion.xml.
In some cases, it doesn't, but it does whenever possible. It cannot resolve XML entities, so it surely doesn't update these ones. And I agree, updating the version.xml file would certainly be useful and it would be possible to implement.
I am extremely reluctant to amend XML markup, deviating from a standard schema just to accommodate tooling. Tooling is meant to help us, not force us to do things in a way that makes it easy for the tooling to achieve it's goal.
Just to clarify: I'm completely fine to change how tooling works for the better, that's completely fine, and happened a lot of times already. I suggested these changes because tooling currently cannot do its job properly. And if it cannot do its job properly, then I cannot do it either. That's the main problem: it becomes more difficult to track and fix outdated content in the manual if the manual cannot be directly generated based on stubs. So ultimately, it's not about the tooling's goals, it's about ours. I've already fixed literally thousands of signatures, which wouldn't have been possible if tooling didn't work well.
All in all, I don't have a good enough idea how the current,
enumitemdescriptionbased approach would allow us to continue to semi-automatically update the documentation with minimal manual changes. I mean, it'll try to extract the description from the manual if all the other ideas are rejected, but this is the last resort, as this is a very cumbersome and not the most future-proof way to achieve what I want.I've just updated php/php-src#21469 so that it keeps the original
enumitemdescriptionelement. And then I could file php/doc-en#5443.
Following the most basic of supports in #179 I think it is necessary to improve it:
<type>and<enumname><enumidentifier>and possibly<constant>(Add linking support for enumidentifier elements #234)