Docstrings considered too complicated

[mk]

Roy Smith wrote:

> /**
>  * Tracing facility. Writes the message to the specified output stream.
>  * If output stream is NULL, writes the message to the process log.
>  *
>  * @param  msg_id  The message id to use for lookup.
>  * @param  ostr    The output stream.
>  * @param  p1      The first substition parameter.
>  * @param  p2      The second substition parameter.
>  * @param  p3      The third substition parameter.
>  * @param  p4      The fourth substition parameter.
>  * @param  p5      The fifth substition parameter.
>  * @param  p6      The sixth substition parameter.
>  * @param  p7      The seventh substition parameter.
>  * @param  p8      The eigth substition parameter.
>  * @param  p9      The ninth substition parameter.
> */

Well at least they did explain something. ;-) You should be happy you 
don't have to deal with PHP programmers that tend to write 
20-positional-argument function AND programmer 1 knows what params 1-7 
do, programmer 2 knows what params 8-15 do and nobody knows what params 
16-20 do.

Seriously.

Regards,
mk