Comments on: On the Perils of Inline API Documentation http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/ PHP Programming, Web Development, PHP Advocacy and PHP Best Practices. Sat, 11 Feb 2012 14:53:56 -0500 http://wordpress.org/?v=2.8.6 hourly 1 By: Glen Hollinger http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86690 Glen Hollinger Thu, 09 Feb 2012 14:56:25 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86690 Its like you study my mind! You seem to know so considerably about this, like you wrote the book in it or something. I feel that you simply could do with some pics to drive the message household a little, but as an alternative of that, this really is fantastic blog. A fantastic study. I'll absolutely be back. Its like you study my mind! You seem to know so considerably about this, like you wrote the book in it or something. I feel that you simply could do with some pics to drive the message household a little, but as an alternative of that, this really is fantastic blog. A fantastic study. I’ll absolutely be back.

]]> By: Newton Boudoin http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86433 Newton Boudoin Tue, 10 Jan 2012 12:04:09 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86433 Is there any service which allows live conversion and streaming of the audio on the go? Is there any service which allows live conversion and streaming of the audio on the go?

]]> By: Chaussre Air Jordan http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86071 Chaussre Air Jordan Mon, 14 Nov 2011 08:51:52 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86071 vue de face montrant sur un fond blanc. Le visage doit être comprise entre 1 et 1 3 / 8 pouces à partir du menton au sommet de la tête. Chapeaux, coiffures et uniformes, sauf mot de vêtements religieux quotidiens ne peuvent pas être portés. vue de face montrant sur un fond blanc. Le visage doit être comprise entre 1 et 1 3 / 8 pouces à partir du menton au sommet de la tête. Chapeaux, coiffures et uniformes, sauf mot de vêtements religieux quotidiens ne peuvent pas être portés.

]]> By: Acheter Nike Air Max http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86070 Acheter Nike Air Max Mon, 14 Nov 2011 08:51:34 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-86070 dédouanement. Bon de réduction peut être eu avec ces magasins si vous êtes disposé à régler pour les gants dédouanement. Bon de réduction peut être eu avec ces magasins si vous êtes disposé à régler pour les gants

]]> By: brinkmann gas grill http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-85855 brinkmann gas grill Mon, 31 Oct 2011 20:27:11 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-85855 You made some very good points there. I researched this matter and found out that a good number of people will agree with your blog. You made some very good points there. I researched this matter and found out that a good number of people will agree with your blog.

]]> By: kevinxiao http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-85143 kevinxiao Tue, 03 Aug 2010 19:04:32 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-85143 I only write more detailed documentation, when i leave the standard path of doing things. I only write more detailed documentation, when i leave the standard path of doing things.

]]> By: my blog http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-84600 my blog Thu, 02 Jul 2009 12:37:11 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-84600 <strong>check this out...</strong> this is mine... check this out…

this is mine…

]]> By: Philipp Scheit http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-83568 Philipp Scheit Sun, 30 Mar 2008 10:40:58 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-83568 I fully agree to the point, that doc blocs can be very annyoing while coding, but as said above meta data is one aspect, that is very important. I think it's better to concentrate on the "important" Doc Blocs - which are on class Level and Method level. Well named properties (and params) can be left with a minimum of documentation. I only write more detailed documentation, when i leave the standard path of doing things. For example i've got a lot of DB ids in my classes - which are always Integer greater 0 and can't be negative. That's why i often only put the "@return" and the "@param $param" information into my documentation, because in phpDocumentor the "getId()" getter would return void as default. /** * @return int */ public function getId() { .. /** * @param int $id */ public functiion setId() { ... easy to read and doesn't waste much time.. I fully agree to the point, that doc blocs can be very annyoing while coding, but as said above meta data is one aspect, that is very important.

I think it’s better to concentrate on the “important” Doc Blocs – which are on class Level and Method level. Well named properties (and params) can be left with a minimum of documentation. I only write more detailed documentation, when i leave the standard path of doing things.
For example i’ve got a lot of DB ids in my classes – which are always Integer greater 0 and can’t be negative. That’s why i often only put the “@return” and the “@param $param” information into my documentation, because in phpDocumentor the “getId()” getter would return void as default.

/**
* @return int
*/
public function getId() { ..

/**
* @param int $id
*/
public functiion setId() { …

easy to read and doesn’t waste much time..

]]> By: Aaron Saray http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-81896 Aaron Saray Sun, 17 Jun 2007 00:28:10 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-81896 A technique I use for generating API documentation is using the '@access' tag. This allows me to put some comments as @access private - which doesn't get included in some documentation (if you compile your documentation with specific switches). A technique I use for generating API documentation is using the ‘@access’ tag. This allows me to put some comments as @access private – which doesn’t get included in some documentation (if you compile your documentation with specific switches).

]]> By: Premature Optimization » Premature Optimization and The Web http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-81467 Premature Optimization » Premature Optimization and The Web Mon, 07 May 2007 19:35:31 +0000 http://www.procata.com/blog/archives/2007/04/13/on-the-perils-of-inline-api-documentation/#comment-81467 [...] These thoughts are not revolutionary, but I think they make an important note, especially today when code generation is so popular, PHP source code to C extension conversion pops up again, and claims that source code documentation is overrated are heard (here and here). [...] [...] These thoughts are not revolutionary, but I think they make an important note, especially today when code generation is so popular, PHP source code to C extension conversion pops up again, and claims that source code documentation is overrated are heard (here and here). [...]

]]>