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. ;)
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
