Phpdocumentor: Please revert the drop of XML template

[redaxmedia]

Hello folks,

I'm pretty sure there is a good reason you removed the XML template and XML writer.

Anyway, the documentation of my CMS is based on the structure.xml - I was forced to use dev-master for years as 2.x does not support latest PHP versions.

I'm super happy to see that you finally release 3.x but removing the XML support now puts me in the super bad situation that my website no longer has API docs.

So... Please consider to revert that decision.

Thank you

[mvriel]

We needed to radically simplify the codebase in order to ensure we can maintain the project with the capacity that we have, and focus on the pivot that we want to do to be able to be a provider of all sorts of documentation.

One of the things I am considering is to reintroduce the generation of the structure.xml not by reintroducing the XML writer; but by adding a twig-based template that renders XML output.

I have proposed this in the team and we are currently taking this course into consideration. I will update this issue as soon as there is a clear decision

[redaxmedia]

We needed to radically simplify the codebase in order to ensure we can maintain the project

I am 100% with you guys

In case you want my support for development. It needs just a scaffolding test with basic setup + xml data provider and I can work against this using the TDD approach.

[oliverschloebe]

+1 for bringing back the structure.xml file.

[jaapio]

If the referenced commit build passes a nightly build should be available in github actions for download. It will contain a new template named xml. which will give you the structure file like you had before.

Or just install phpDocumentor with composer if that works for you :-)

Please let me know if this fits your needs.

[jaapio]

https://github.com/phpDocumentor/phpDocumentor/suites/504075807/artifacts/2606839 the download can be found here.

[oliverschloebe]

@jaapio Thanks so much for bringing the structure.xml file/template back!

After a quick run I noticed the line numbers not being correctly filled, e.g. <docblock line=""> is either empty or 0 when parsing the WordPress trunk which worked before. Same for <argument line=""> tags.

edit 1 Also worth noting I do get several warnings while running phpdoc like

WARNING   [php] Notice: Array to string conversion ["exception" => ErrorException { …}]

but I havn't been able to track down the issue here.

edit 2 Seems like most <description> and <long-description> tags for function <docblock> nodes are empty even though there are descriptions. Maybe due to the issue mentioned in edit 1?

[jaapio]

Thanks for your feedback. I will investigate what is going on.

[oliverschloebe]

Thanks for your feedback. I will investigate what is going on.

Thank you! If you need both the new and older structure.xml files (containing data from the same project) for comparison reasons, just let me know.

[jaapio]

The old file will help me to see the differences easier.

[oliverschloebe]

https://send.firefox.com/download/5467e7c0cfbde622/#XP4JlflFbYCehSzE9FXTtQ :v:
_(FYI, expires after 5 downloads or 7 days)_

[oliverschloebe]

As for the missing line numbers and <argument> nodes inside the <function> nodes this line has an error: https://github.com/phpDocumentor/phpDocumentor/blob/d0535baf35e768c285c4273cb5cc473d16aa9816/data/templates/xml/structure.xml.twig#L21

should be

{{ include('docblock.xml.twig', {descriptor: function}) }}

The <argument> nodes are still faulty, even though the argument.xml.twig template looks fine to me (from a noob perspective).

[jaapio]

I fixed a number of issues in the xml template. The output is not 100% equal to what you got from v2, as said before a lot has been changed.

Please report new issues when you are missing something in the new template. I'm closing this one because everything that has been asked for is now done. We are working towards a v3 final release, and after that more stable releases will follow in a shorter time. Allowing us to add information to the template and fix issues you are reporting.

Thanks for all the feedback you gave until now, I'm looking forward to seeing new issues coming whenever you have a problem with phpDocumentor.

[oliverschloebe]

Thanks @jaapio for your work so far! ❤️ I'll be testing your changes soonish and will open new tickets when necessary (and maybe even provide fixes myself).

Thanks again for bringing structure.xml back!

[redaxmedia]

@jaapio You took the evidence to care about the community, thank you so much for listening.

I was able to generate the API documention for my CMS based on the master branch of phpDocumentator. Looking forward to the next release candidate!

Bug report: Type and Description are missing for the fields / properties of classes.

[jaapio]

Without a community we are nowhere. I'm doing this work just for people like you. Not listening is not an option.

Could you please report a new issue for the bug you found? I won't be able to fix it quite soon. And I might forget to do that.