Iako sjajan alat (ako ga ne koristite, pravac na www.phpdoc.org za više informacija) upravo sam naleteo na problem koji ne znam kako da elegantno rešim.

Naime, u projektu na kojem sada radim postoji par klasa koje implementiraju singleton pattern. Kao što verovatno znate, tada se umesto konstruktora klase za dobijanje objekta poziva jedan static metod klase.

Zavisno od nekih parametara, u kod hoću da uvedem jednu od dve različite implementacije klase koje se samo neznatno razlikuju. Logično, napraviću jednu abstract klasu i iz nje izvesti dve različite klase koje imaju potrebne razlike u odnosu na baznu klasu.

Pošto sada imam dve različite klase koje implementiraju singleton pattern to znači da je i sintaksa njihove konstrukcije različita. Ja hoću da na početku koda očitam parametre poziva, odlučim se za jednu od dve varijante i onda da ih onda koristim na jedinstven način. Razmišljam dalje i pomislim da zavisno od parametara mogu da učitam datoteku sa tačno jednom implementacijom tako da uvek pri izvršavanju imam u kod uključenu baznu klasu i samo jednu njenu naslednicu. Onda mogu da iskoristim isto ime za obe varijacije (pošto se u kodu pojavljuje uvek samo jedan slučaj pri svakom izvršavanju) i da imam isti pristup nevezan od varijacije koju sam učitao.

Međutim, tu dolazi problem sa phpDocumentor-om. Svaka klasa ima drugu @subpackage oznaku, čak sam probao da uvedem i @name oznaku sa različitim vrednostima ali to ne vredi. On uvek prijavi:

WARNING: duplicate class element "db" in file appserver/_core/db_normal.class.php will be ignored. Use an @ignore tag on the original if you want this case to be documented.

Ja sada mogu da ga poslušam i prvo generišem dokumentaciju, onda postavim @ignore nad prvom klasom, i zatim ponovo generišem dokumentaciju. Pošto su klase u različitim podpaketima njihova dokumentacija se nalazi u različitim direktorijumima tako da neće doći do prepisivanja, a meni ostaje da na kraju ručno izmenim listu svih klasa i dodam link ka prvoj klasi. Očigledno, ovo nije elegantno rešenje, a još gore je problem rešiti pri egzotičnijim opcijama izvoza dokumentacije.

Ukoliko se ne setim nekog dobrog razloga zašto phpDocumentor treba da ignoriše klase istog imena koje se nalaze u različitim paketima, sutra ću poslati Bug Report. Naravno, ako je neko naleteo na sličan problem neka slobodno kaže rešenje pošto je sigurno bolje od ovoga što sada radim.