Using PHPDocumentor to document the magic functions.
in [PEAR]
|
Prev: [ANNOUNCEMENT] Structures_LinkedList-0.2.1 (beta) Released.
Next: [ANNOUNCEMENT] Mail_Mime-1.6.0RC2 (beta) Released.
From: Richard Quadling on 12 Jan 2010 06:46 Hi. To implement public readonly properties you can use getX(), getY(), getZ() methods (which then access the private vars) or you can use __get($var) to consolidate/simplify the number of methods. With the discrete getters() it is easy to docblock them. Everything is obvious, but there is a LOT of duplicate code and documentation. But how do you docblock __get()? With the magic functions __get(), __set(), __call(), __callStatic(), they act as proxies. It is NOT the proxy itself that is normally wanted to be documented (maybe in a cursory manner), but what is being proxied. If you are creating a WSDL file for SOAP and have __get() and __call(), then you would want to document each entry but without the code duplication. What is the best approach? Regards, Richard Quadling. -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling
From: Richard Quadling on 12 Jan 2010 07:30
2010/1/12 Jochem Maas <jochem(a)iamjochem.com>: > Op 1/12/10 12:46 PM, Richard Quadling schreef: >> Hi. >> >> To implement public readonly properties you can use getX(), getY(), >> getZ() methods (which then access the private vars) or you can use >> __get($var) to consolidate/simplify the number of methods. >> >> With the discrete getters() it is easy to docblock them. Everything is >> obvious, but there is a LOT of duplicate code and documentation. >> >> But how do you docblock __get()? >> >> With the magic functions __get(), __set(), __call(), __callStatic(), >> they act as proxies. It is NOT the proxy itself that is normally >> wanted to be documented (maybe in a cursory manner), but what is being >> proxied. >> >> >> If you are creating a WSDL file for SOAP and have __get() and >> __call(), then you would want to document each entry but without the >> code duplication. >> >> >> What is the best approach? >> > > this is a difficult problem, probably no real answer to it right now. > I vaguely remember Derick Rethans mailing about this issue in regard to > the ezComponents lib ... you might want to check that codebase for inspiration > and or STW for what he had to say on the matter. > >> >> Regards, >> >> Richard Quadling. >> > > @property and @method are my friends. Gee! Wood for trees. Thanks. -- ----- Richard Quadling "Standing on the shoulders of some very clever giants!" EE : http://www.experts-exchange.com/M_248814.html Zend Certified Engineer : http://zend.com/zce.php?c=ZEND002498&r=213474731 ZOPA : http://uk.zopa.com/member/RQuadling |