[PHP] Re: Doc standard for methods?
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
Re: [PHP] Re: Doc standard for methods?
On Tue, Jan 27, 2009 at 10:00 AM, Kyle Terry k...@kyleterry.com wrote:
On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham nrix...@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. ;)
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
Re: [PHP] Re: Doc standard for methods?
On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham nrix...@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
Re: [PHP] Re: Doc standard for methods?
On Tue, Jan 27, 2009 at 7:06 AM, Eric Butera eric.but...@gmail.com wrote:
On Tue, Jan 27, 2009 at 10:00 AM, Kyle Terry k...@kyleterry.com wrote:
On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham nrix...@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 ... FNE!
--
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
Re: [PHP] Re: Doc standard for methods?
Kyle Terry wrote:
On Tue, Jan 27, 2009 at 7:06 AM, Eric Butera eric.but...@gmail.com wrote:
On Tue, Jan 27, 2009 at 10:00 AM, Kyle Terry k...@kyleterry.com wrote:
On Tue, Jan 27, 2009 at 5:56 AM, Nathan Rixham nrix...@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 ... FNE!
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!
--
PHP General Mailing List (http://www.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
