R devel - May 2005 - Form of \item{arg_i}{Description of arg_i.} in \arguments

Hello!

This really isn't so important, but it comes often in my mind, when
I write documentation for functions. Writing R Extensions manual says
that one should describe each element of the argument list (which is
afcourse OK) in a form:

\item{arg_i}{Description of arg_i.}

When I started with R it really helped me that some "man pages" used

\item{arg_i}{Mode. Description of arg_i.}

e.g. 

\item{argument1}{Logical. Bla bla bla.}
\item{argument2}{Integer. Bla bla bla.}
\item{argument2}{Character. Bla bla bla.}

Although one can most of the time deduce from the man page what mode 
should each argument be, I belive that it would enhance redeability 
if mode specification would be mandatory. I would also like to see 
that there is some sort of mandatory form i.e.

\item{argument2}{Character. Bla bla bla.}
                 ^a       ^b^c         ^d

a - lower or upper case
b - dot or colon or semicolon
c - lower or upper case
d - dot?

I understand that taking this as mandatory or proposed form, would 
probably make a lot of man pages "invalid", but it would enhance 
redeability on longer term.

Comments, thoughts, ...?

Lep pozdrav / With regards,
    Gregor Gorjanc

----------------------------------------------------------------------
University of Ljubljana
Biotechnical Faculty        URI: http://www.bfro.uni-lj.si/MR/ggorjan
Zootechnical Department     mail: gregor.gorjanc <at> bfro.uni-lj.si
Groblje 3                   tel: +386 (0)1 72 17 861
SI-1230 Domzale             fax: +386 (0)1 72 17 888
Slovenia, Europe
----------------------------------------------------------------------
"One must learn by doing the thing; for though you think you know it,
 you have no certainty until you try." Sophocles ~ 450 B.C.