Re: Re: Doc standard for methods?

Kyle Terry wrote:

On Tue, Jan 27, 2009 at 7:06 AM, Eric Butera <eric.butera@gmail.com> wrote:

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. ;)

Never said we used it :) Remember my coworkers responce ... "FIIIINE!"

and I want to know more, do you mean.. class egg { private function whatever() { echo __METHOD__ . PHP_EOL; } protected function wherever( $e ) { $e->whatever(); } public function whenever( $e ) { $this->wherever($e); } } $a = new egg; $b = new egg; $a->whenever($b); ?? regards!