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
