Add non-parameter attribute rendering

[haszi]

Enable rendering of attributes for classes, exceptions, interfaces, methods and functions. The implementation feels a little off but it seems to work as intended (see attached test attribute_formatting_002.phpt).

I've also found a mistake I've made in the test attribute_formatting_001.phpt where the parameter attribute was outside of the <methodparam> element. I've corrected this by moving the attribute inside the element.

[Girgias]

Thank you! I'd like the opinion of @TimWolla and @kocsismate about the generated XHTML

[TimWolla]

I don't have an opinion. I trust that you generate XHTML that looks good 😄

[haszi]

Function attributes were not rendering properly and there was no test for them either so I just pushed a commit to fix this.

[haszi]

Attributes of class, exception and interface synopses are rendering like this:

[haszi]

Attributes of methods

and functions

[TimWolla]

I would prefer having a newline between every attribute as well.

[haszi]

I would prefer having a newline between every attribute as well.

Something like in the below screenshots?

Classes/exceptions/interfaces:

Methods:

Functions:

[TimWolla]

Something like in the below screenshots?

Yes, looks great to me. Thank you.

[haszi]

I've just pushed the commit to render every attribute on its own line (just like in the last set of screenshots).

[kocsismate]

Thank you! I'll implement the required gen_stub.php related changes

[TimWolla]

Thank you! I'll implement the required gen_stub.php related changes

I believe this never happened, did it?

[cmb69]

In a perfect world, there wouldn't be the need for any changes to gen_stub.php; Docbook should ideally render indepent of the source code formatting. However, we're not living in a perfect world.

Anyhow, do we even have classes etc. or functions with attributes that are documented. I could only find parameters, but their rendering shouldn't be affected anyway.

[TimWolla]

@cmb69

In a perfect world, there wouldn't be the need for any changes to gen_stub.php; Docbook should ideally render indepent of the source code formatting. However, we're not living in a perfect world.

I don't follow. gen_stub.php is used to keep the documentation in sync with the actual code by leveraging the stubs. I'm not sure what this has to do with source code formatting.

Anyhow, do we even have classes etc. or functions with attributes that are documented.

We have: All the attribute classes (and with PHP 8.4 all the deprecated functions and methods). The attribute markup is not yet included in the documentation, because of gen_stub not yet having support for generating it (and because understandably no one bothered to do it by hand).

[cmb69]

I don't follow. gen_stub.php is used to keep the documentation in sync with the actual code by leveraging the stubs. I'm not sure what this has to do with source code formatting.

Ah, sorry, I misunderstood. I thought this was about rendering attributes on separate lines; and that shouldn't require changes to gen_stub.php (but would have had, if gen_stub.php would have already output DocBook with attributes on the same line).

because of gen_stub not yet having support for generating it (and because understandably no one bothered to do it by hand).

And none bothered to improve gen_stub.php either. ;) My stance on automation: great to have it, but if none is available, do it manually, unless that is so much work, that you do the automation upfront. (hmm, guess I just volunteered ;)

[kocsismate]

I believe this never happened, did it?

Oh, no, I believe I forgot about it at last. :(

[kocsismate]

Finally I filed php/php-src#16926 :)