Last December, I struggled with documentation tags while using Eclipse with a private PHP project. I eventually realized Eclipse wasn't necessarily the one to blame. The specification for PHPDoc's @param tag is found in PSR-19, a standard recommendation published by the PHP Framework Interoperability Group. According to that specification, many @param tags would be ambiguous, since the last 2 elements are optional. The tags with which Eclipse struggled were such ambiguous tags, but the real problem was the specification.

I was quite surprised to find such a serious issue, but went to check its status. I then had an even greater surprise: I could not find the issues reported in PSR-19. Or for that matter, any of the PHP Standard Recommendations.

At that point, I joined the php-fig group and - not knowing a proper way to do so - reported the meta-issue on that mailing list.

In the following months, I saw significant activity on the mailing list, from a significant number of contributors, but no answer to my question. Nor any reference to an ITS. In August, as the issue persisted, I simply "bumped" the thread (repeated my question).

Unfortunately, it has now been 9 months since my report, and the problem is still the same as far as I can see. I was going to add that I still don't know if my PSR-19 issue was reported, but in fact, I noticed while writing this post that Ben Mewburn reported the PSR-19 problem 2 months before I joined the group. Why was nothing done? Simply because... just like me, it seems he reported nowhere else than on the mailing list!

I love Javadoc, and PHPDoc is very important. Some PSR-s are very valuable, and I find it most unfortunate to give up on a major PHP institution, but as such an issue now has apparently persisted for over 4 years, and as there was no progress months after reports, I prefer not to remain associated with the FIG, and am hereby announcing I will no longer contribute to the PHP FIG - and therefore to PHP Standard Recommendations - unless required to.

As for the initial issue, I will live with it - but I'll recommend my customers/employers to avoid PHP For instance, Javadoc's equivalent @param tag doesn't have that issue. For a very simple reason: it doesn't have to specify the type, which is already in the function definition - where it should be.