On Tue, Jan 27, 2009 at 7:06 AM, Eric Butera <eric.butera@xxxxxxxxx> wrote:
> On Tue, Jan 27, 2009 at 10:00 AM, Kyle Terry <kyle@xxxxxxxxxxxxx> wrote:
>> 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
>>
>>
>
> And I called it haxx. ;)
>
Never said we used it :) Remember my coworkers responce ... "FIIIINE!"
--
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
