Proposal for Enum markup

[Girgias]

Part of: #2796

Fixes:

• Random\IntervalBoundary enum is not documented #3074

Requires:

• Migrate PHP Documentation schema to DocBook 5.2 #3326
• PhD support to render it like an enum (enum rendering. phd#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?

[TimWolla]

Can't comment on the Docbook specifics, but here's some words for you to include to make the page useful right from the start.

[haszi]

@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:

[TimWolla]

@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.

[kocsismate]

Hmm, so far classsynopsis elements only contained the signature itself, but not the descriptions. Is it intentional that it's different for enumsynopsis elements?

[Girgias]

The DocBook 5.2 markup describes the markup in that manner: https://tdg.docbook.org/tdg/5.2/enumsynopsis (via the <enumitem> tag) so yes.

For reference, the <classsynopsis> description is located here: https://tdg.docbook.org/tdg/5.2/classsynopsis

[kocsismate]

That's a pity, because this way automatic replacement is going to be much more difficult, since there are free form values in the generated enumsynopsis item, and we should somehow try to preserve them.

[Girgias]

That's a pity, because this way automatic replacement is going to be much more difficult, since there are free form values in the generated enumsynopsis item, and we should somehow try to preserve them.

I'm not sure whether that's difficult? One just needs to ignore the <enumitemdescription> tag, but also, I don't see how an enum would change after it has been introduced.

[kocsismate]

classsynopsis elements are generated based on the current stub definitions for each class/interface/enum signature which are encountered on class synopses pages (https://github.com/php/php-src/blob/0ad2e4d997549c85aac61120a94ea3da0b709339/build/gen_stub.php#L5560) and then the respective elements are replaced altogether one by one (the replaceAndCompareXmls() call a few lines below).

This means that if there is anything inside classsynopsis elements which are not generatable based on the definitions in stubs, then those things will be removed. A workaround for enums could be that the enum case descriptions are retrieved from the manual pages and they are inserted into the generated elements... This complicates the process, but maybe it's not that difficult if this is going to be the preferred approach.

Also, It has just came to my mind that these descriptions would result in enum definitions which are completely not valid PHP code 🤔 while for the rest of the symbols, we generate at least a remotely valid PHP code since a few years.

[kocsismate]

Just a FYI: we should also think about the markup for implemented interfaces, enum constants, methods

[Girgias]

Right... I forgot that PHP enums can do this sort of stuff...

[kocsismate]

Yeah, and I've just realized that e.g. fieldsynopsis elements inside enumsynopsis are not even allowed in DocBook. :/ (Or are they?)

[Girgias]

Yeah, they are not, because DocBook (rightfully) assumes that enums are just that, and not our weird thing based on objects.

I think we might need to use the <classsynopsis> tags when an enum has constants, properties, or methods. However, I would imagine this to be rare for internal enums.

[kocsismate]

Other types of symbols have a dedicated section title for classes and interfaces. Would it be a good idea to add them for enums as well?

[kocsismate]

I've just drafted a PR which adds support for this feature in stubs: php/php-src#14369 I intentionally modified Random\IntervalBoundary and also checked in the generated result for testing purposes.

[haszi]

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?

[kocsismate]

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.

[TimWolla]

This will now also be required for RoundingMode (and some other enums) in 8.4.

[cmb69]

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).

[Girgias]

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).

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".

[cmb69]

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.

[Girgias]

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.