Re: Re: Doc standard for methods?

On Tue, Jan 27, 2009 at 10:00 AM, Kyle Terry <kyle@kyleterry.com> wrote: > On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham <nrixham@gmail.com> 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. ;)