[Phpmyadmin-devel] On the @uses comment tag

[Marc Delisle]

Michal Čihař a écrit :
> Hi
> 
> Dne Tue, 21 Jun 2011 07:52:31 -0400
> Marc Delisle <marc at infomarc.info> napsal(a):
> 
>> Michal Čihař a écrit :
>>> Hi
>>>
>>> Well there are many ways to remove it, but the question is whether we
>>> want to :-).
>> I am reluctant to remove all @uses but I agree to remove the reference 
>> to internal PHP functions.
>>
>> Of course it's more work to maintain but I think that if we adhere to 
>> phpDocumentor principles, we should use @uses. Many people need to work 
>> with the source code and understand it.
> 
> I still fail to see what added value does it bring - somebody reading
> documentation and looking what function does does not really care what
> it uses underneath. For somebody working with the code, it only brings
> extra effort to keep it up to date.

Here are situations I can think of:
- someone changing parameters for a function; it would be interesting to 
see where this function is called
- someone changing the format of a session variable or a global and 
wanting to see where this is used

Does DocBlox answers these questions currently, if @uses is used? I 
believe that phpDocumentor did.

-- 
Marc Delisle
http://infomarc.info