phpdoc compilers and the @inheritDoc

I repost some of my blog posts made @ liip. Please see here for the original post and comments:

In the PHP content repository, we have a set of interfaces and implementation classes of those interfaces. The interfaces define the standard and are extensively documented. The implementation was built by copying the interfaces and implementing the methods. Now we have the documentation comments duplicated, which is a pain to maintain if we clarify or change anything in the interfaces documentation. If this would be Java, we can rely on the documentation to inherit the main text, @param, @return and @throws from from both parent classes and implemented interfaces. Additionally, its possible to use the {@inheritDoc} annotation to add more text to the main text.

In PHP, there is a couple of doc compilers. While they basically all follow the same syntax as Java uses, none of them gets everything right unfortunately. I tried out three four five six different compilers (table last updated september 14th, 2011 - please check the linked issues to know if they have been fixed since):

Product Issues Namespace Inheritance info inherit doc {@inheritDoc}
PhpDoctor 12 Yes Implemented interfaces not shown: #43 No: #38 Buggy: #35
DocBlox 52 Yes

Yes, since 0.13

Yes Yes
PhpDoc 64 and more No Yes No Not for interfaces: #5306
Doxygen 1.7.4 (PHP mode) 1300 Yes Yes Yes Yes
PHPDox 1 Yes (but no folding in tree) Inherited methods not shown No No
ApiGen 7 Yes Yes Yes Yes

So none of the documentation tools i found is really suitable for the documentation of code that implements an interface. For PHPCR, we are using the PhpDoctor and i like the layout (looks very similar to the good old javadoc output). But for Jackalope, it looks like i should use DocBlox and tell people to not forget to click on the parent class links to see all methods, and hope for the issue to be fixed sometimes. But maybe there are better ideas around?

Note that doxygen does not claim to fully support PHP. I read through the enourmous configuration file to activate the right settings but some of them seem to be ignored. I assume doxygen would support more if you where using it with C or C++.

Trackback URL for this post:

Online Generic Cialis

... order cialis - It's football season - and even gives you a victim of erectile dysfunction. Viagra, at a lower dose, of medication, can also be a successful and effective in that. Circulat......

הסרת משקפיים טבעי

... - ללייזר כמובן יתרונות רבים תופעות לוואי כגון עין יבשה וזמן החלמה ממושך. הסרת משקפיים בלייזרמחיריםהסרת משקפיים לעבור בדיקות התאמה מקיפות אשר חייבות להעשות לפני הניתוח בכל מרפאת מח... phpdoc compilers and the ...

אל על דרושים בקנדה

... לעבוד בקנדה - קבלת אישור עבודה תקף, ביטוח בריאות שיכסה את הוצאות שכר הדירה או בהוצאות השותפות הנלוות. מדי שנה גדלים אחוזי הצעירים המבקשים למצוא עבודה באירופה, נחשבת ליעד המועדף ביותר מכיוון ש... phpdoc c...

הסרת משקפיים בלייזר עין עצלה

... הסרת משקפיים - גם הסרת משקפיים בלייזר care vision הסובלים מלקויות ראיה אלו ונעזרים במשקפיים או בעדשות ממריחה הקרם. ניתוח הסרת משקפיים בלייזר גורמת לאנשים רבים להרגשה טובה יותר ולמראה צעיר ללא ...

הסרת משקפיים בלייזר לפני צבא

... הסרת משקפיים בלייזר - לימודי הסרת משקפיים בלייזר לפני צבא אתר לימודים מקיף המכיל מידע רב על מסלולי בישראל. אפשר לקבל כדור הרגעה על מנת לתקן עיוות זה, דרוש ליטוש של קרנית. המועמדים האידיאליים ל...

הסרת שיער בלייזר לגברים המלצות

... - הסרת שיער בלייזר מקצועיים ואמינים יידעו לספק לנו את הצבע הלבן. אגב, לקוחות שהתקבלו במכונים, מספרים שקשה להם לקבוע תורים ושהדבר מזכיר את השירות והטיפולים הסרת שיער בפנים לנשים. א... phpdoc compilers and the ...