# [Rd] Form of \item{arg_i}{Description of arg_i.} in \arguments

Gorjanc Gregor Gregor.Gorjanc at bfro.uni-lj.si
Mon May 16 15:27:36 CEST 2005

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.

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.