Documentation: list all supported config file file names and precedence

[jrfnl]

Related to / follow-up to #1997

I'm a little confused about the default supported configuration file names.
Based on the current documentation for v3, these would be phpdoc.dist.xml and phpdoc.xml.

The first one of these, to me, is surprising, as other "tooling" applications in the PHP sphere, like PHPUnit and PHPCS, use the reverse order for the file extension, so I would expect phpdoc.xml.dist.

Reversing the extensions based on what they are used to from other tools, would be a typical and easy mistake for people to make and I imagine it would be helpful not to receive support requests for this situation.

If I understood issue #1997 correctly, the filename phpdoc.xml.dist is now supported in phpDocumentor 3 ?

Based on that, I believe:

• The fact that this is now supported should be mentioned in the changelog.
• The documentation needs to be updated to include the third supported file name.
• The documentation would need to make a clear statement about the precedence of the file names.

In issue #1997 I did see a mention that the file precedence / file loading order needs to be determined, but I couldn't find a decision on how the precedence/ fileorder has been implemented.

To me, the logical order would be as follows, but I haven't tested whether this is the reality or not:

• phpdoc.xml
• phpdoc.dist.xml
• phpdoc.xml.dist