php
Proposal for Enum markup
Part of: https://github.com/php/doc-en/issues/2796
Fixes:
- https://github.com/php/doc-en/issues/3074
Requires:
- https://github.com/php/doc-en/issues/3326
- PhD support to render it like an enum (https://github.com/php/phd/issues/89)
I kinda wish I could use a <refentry> tag instead, but we need to insert this into a <book> element which requires an intermediate tag anyway, so steal the suboptimal markup from classes.
@haszi do you think this makes sense, and is this not too complicated to add support to PhD for it?
@haszi do you think this makes sense, and is this not too complicated to add support to PhD for it?
This is very much in line with the new class markup you used which is great. PhD support should not be an issue and most of the work will be done when the new class markup is converted.
I assume the rendered enum synopsis would look something like this:
@haszi Note that related to #3405, enum cases can also have attributes (they are class constants internally). So it's probably to take that into account right away.
I've just drafted a PR which adds support for this feature in stubs: https://github.com/php/php-src/pull/14369 I intentionally modified Random\IntervalBoundary and also checked in the generated result for testing purposes.
Since all enums implement either the UnitEnum or the BackedEnum interface and inherit their default method implementation, all enum markup will have to include both an <enumsynopsis> and a <classsynopsis> element. Neither of these can have the other as its child but we could have one after the other in the synopsis <section> like this (I think this is valid DocBook 5.2 markup):
<section xml:id="enum.intervalboundary.synopsis">
&reftitle.classsynopsis;
<enumsynopsis>
... // enum (cases) markup
</enumsynopsis>
<classsynopsis>
... // regular class markup
</classsynopsis>
</section>
<enumname> in the <enumsynopsis> element would define the enum's name and any class/interface name in the <classynopsis> element would be ignored.
What do you think?
in the element would define the enum's name and any class/interface name in the element would be ignored.
Hmm, interesting option... I wouldn't have thought about it. But I think I'd prefer to just have one element which has to be classynopsis because of the restrictions we face.
This will now also be required for RoundingMode (and some other enums) in 8.4.
Hmm, this is ugly. We can't use <enumsynopsis> due to its limitation, and we can't use <classsynopsis> because its class attribute only supports "class" and "interface". I'm afraid we need to redesign enums altogether. ;)
Okay, let's be pragmatic and use <classsynopsis> (and role="enum" if necessary).
Hmm, this is ugly. We can't use
<enumsynopsis>due to its limitation, and we can't use<classsynopsis>because itsclassattribute only supports "class" and "interface". I'm afraid we need to redesign enums altogether. ;)Okay, let's be pragmatic and use
<classsynopsis>(androle="enum"if necessary).
We will need the role="enum" as otherwise the generated markup by PhD will make it look like classes.
I still don't think any internal enum is going to actually implement interfaces or have any sort of properties, even if this is allowed in userland. So the "problem" seems rather theoretical, and even then it would be possible to add the above "hack fix" with the role="enum".
I still don't think any internal enum is going to actually implement interfaces or have any sort of properties, even if this is allowed in userland. So the "problem" seems rather theoretical, and even then it would be possible to add the above "hack fix" with the
role="enum".
I'm a bit worried about translations. If we have a number of enum documented with <enumsynopsis>, and later need to change everything …
On the other hand, maybe we will never need more, and I'm overthinking.
I still don't think any internal enum is going to actually implement interfaces or have any sort of properties, even if this is allowed in userland. So the "problem" seems rather theoretical, and even then it would be possible to add the above "hack fix" with the
role="enum".I'm a bit worried about translations. If we have a number of enum documented with
<enumsynopsis>, and later need to change everything …On the other hand, maybe we will never need more, and I'm overthinking.
What I meant, is that it would be perfectly fine for both markups to coexist, where the <classsynopsis class="class" role="enum"> usage would be reserved for "complex" enums that actually behave like classes.
Ah and: Should the PR be renamed? It's not just a proposal at this point, no?