Re: Re: Doc standard for methods?

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