Recommendations to others considering phpDocumentor:
I had experience with both Swagger and PHPDoc. Swagger is complex and time-consuming to write documents in. PHPDoc provides only one simple way of writing documents in the middle of the code.
If you are choosing between the two, I would probably suggest PHPDoc.
The only missing feature with the PHPDoc is lacking the support for nested typed arrays as well as key-value arrays. Review collected by and hosted on G2.com.
What problems is phpDocumentor solving and how is that benefiting you?
Source code documenters solve two main problems: "Source code delivery" and "API referencing".
The two well-known documentation tools for PHP are PHPDoc and Swagger.
Swagger provides a more complex solution for documenting the php code. You may either embed the syntax in the middle of the code or just create separate files for the documentation. Classes should be mapped independently which makes it more time consuming to write a document. Even the embedded syntax is hard to write.
On the other hand, the only thing you need to do with PHPDoc is to write your document above your definitions. The syntax is clean, has native support by popular IDEs including PHPStorm, Netbeans, etc. and altogether everything moves super easily. Review collected by and hosted on G2.com.