On Sat, February 10, 2007 5:41 am, Ronald Chmara wrote:
> Scenario one:
> All behavior changes must be documented, this tag is always there,
> and thus not useful.
I beg to differ.
If every change was documented to the degree that it needed
documentation, the tag would be useful still:
USEFUL:
- ops
+ oops
@doc Fixed typo in comments
NOT SO MUCH:
+ /* pretend I typed 40 lines of really hacky C code here */
@doc Frobished the frobisher
> Scenario two:
> Developers decide when changes are "important" enough to be
> documented, and tag as such, in which case we go back to...
>
> Scenario three:
> The problem of developers who don't think documentation is needed for
> their changes.
Is anybody really that... naive?
It seems to me that giving the developer the opportunity to easily
give the Doc Team SOME CLUE what the heck they were thinking is a Good
Idea.
> In the end, I often wonder if this is documentation issue, or a
> developer issue. Developers read the code, and often don't need *any*
> documentation. Our end users read a manual page, and wonder what a
> "bool" or "int" is, as a very large number of our users are fairly
> new to the whole subject matter.
Most of them are in the middle of that...
> (side joke, does PHP have a zool(), destroyer of all world (global)
> variables?)
No, but you can implement this in User Code:
function zool(){
foreach($_GLOBALS as $k => $v){
unset($k);
}
unset($_GLOBALS);
}
:-)
--
Some people have a "gift" link here.
Know what I want?
I want you to buy a CD from some starving artist.
http://cdbaby.com/browse/from/lynch
Yeah, I get a buck. So?
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
