On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham <nrixham@xxxxxxxxx> wrote:
> Larry Garfield wrote:
>>
>> Greetings, all. I am looking for feedback on a documentation question, in
>> the hopes that someone else has found a good solution to an abnormal
>> situation.
>>
>> We're in the process of introducing OOP syntax to a large procedural code
>> base. Our developer base is a mixture of people who are procedural-centric
>> and those that flip between procedural and OOP easily. One area we've run
>> into is documenting some of the more complex OOP interactions. For example,
>> if we have a method chain:
>>
>> foo()->bar()->baz()->narf();
>>
>> some developers have expressed concern in figuring out which narf() method
>> is actually being called, since foo(), bar() and baz() may return objects of
>> different classes (of the same interface) depending on various conditions
>> (the classic factory pattern).
>> Currently, we're including a docblock (Doxygen, close enough to PHPDoc for
>> government work) on the interface or parent class that has full docs, and
>> then nothing on the child classes. My understanding of docblocks is that
>> most documentation parsers prefer that, so that the docblock itself
>> inherits.
>> One suggestion that has been raised is to reference the parent class and
>> factory function in a comment after the method signature. That is:
>>
>> class Narfing_mysql {
>> // ...
>>
>> public function narf() { // Narfing foo()
>> // ...
>> }
>> }
>>
>> So that it can be easily grepped for. That strikes me as a very hacky
>> non-
>> solution. Does anyone else have a recommendation for how to improve such
>> documentation? Is there a standard in PHPDoc that I don't know about? Any
>> other projects doing something like that?
>>
>
>
> first idea would just be to use the @return; if they're using any kind
> decent of ide it'll show the return type; failing that they can check the
> docs
>
> class Narfing_mysql {
> /**
> *
> * @return Type
> */
> public function narf() { // Narfing foo()
> // ...
> }
> }
>
> or not best practice but i dare say
>
> class Narfing_mysql {
> /**
> *
> * @return TypeA, TypeB
> */
> public function narf() { // Narfing foo()
> // ...
> }
> }
>
> or in the method description with @see Class inline links?
>
> regards
>
> --
> PHP General Mailing List (http://www.php.net/)
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>
Eric and I were just discussing something similar yesterday. We
discovered you can make private and protected method calls from two
different instances of the same object type. I personally called this
reference hopping.
--
Kyle Terry | www.kyleterry.com
Help kick start VOOM (Very Open Object Model) for a library of PHP classes.
http://www.voom.me | IRC EFNet #voom
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
