[R] Documenting a function using roxygen2

[Thierry Onkelinx]

Dear Georg,

My 2 eurocents.

- I'd place the Roxygen header just above the function instead of instead
the function. That makes your function more readable.
- Use only tags that Roxygen knows about.
- Use version controle instead of the version, created and updated tags.
- You can specify the author, license and version at the package level.
devtools and Roxygen make it very easy to create a package. Even if it
would contain only one or a few functions.

Best regards,

ir. Thierry Onkelinx
Instituut voor natuur- en bosonderzoek / Research Institute for Nature and
Forest
team Biometrie & Kwaliteitszorg / team Biometrics & Quality Assurance
Kliniekstraat 25
1070 Anderlecht
Belgium

To call in the statistician after the experiment is done may be no more
than asking him to perform a post-mortem examination: he may be able to say
what the experiment died of. ~ Sir Ronald Aylmer Fisher
The plural of anecdote is not data. ~ Roger Brinner
The combination of some data and an aching desire for an answer does not
ensure that a reasonable answer can be extracted from a given body of data.
~ John Tukey

2016-10-11 13:13 GMT+02:00 <G.Maubach op weinwolf.de>:

> Hi All,
>
> I began to document my functions using roxygen2. This is an example of a
> function I would like to write for training and testing purposes:
>
> t_simple_table <- function(variable,
>                            useNA = TRUE,
>                            print = FALSE) {
>     #' @title Create a simple table for one variable.
>     #'
>     #' @description t_simple_table() creates absolute and relative
>     #' frequencies, cumulative sums and column sums for both as well as
>     #' overall statistics about valid N and missing values.
>     #'
>     #'
>     #' @param variable (vector, list, data.frame): variable the table is
>     #' created for.
>     #' @param useNA (logical): flag to include or exclude missing values
>     #' from the computation.
>     #' @param print (logical): flag to print/not print a table before
>     #' returning it as an object.
>     #'
>     #' @operation
>     #' Coerces the given variable to a factor.
>     #' If useNA = TRUE NA is also transformed to a valid value,
>     #' if useNA = FALSE it is disregarded in all operations.
>     #'
>     #' @return Returns a table with the following statistics:
>     #'
>     #' <Variable Name> Frequencies   Percent   Cumulative
>     #'                                         Percent
>     #' Valid                     .         .
>     #' Missing                   .         .
>     #' Total                     .       100
>     #' Categories
>     #'   Cat 1                   .         .            .
>     #'   Cat 2                   .         .            .
>     #'   Cat 3                   .         .            .
>     #'   ...                     .         .          100
>     #'   Total                   .       100
>     #'
>     #' @errorhandling None
>     #'
>     #' @version "0.1"
>     #'
>     #' @created "2016-10-11"
>     #' @updated "2016-10-11"
>     #'
>     #' @status development
>     #'
>     #' @see Manderscheid: Sozialwissenschaftliche Datenanalyse mit R,
>     #' p. 79ff
>     #'
>     #' @author Georg
>     #'
>     #' @license GPL-2
>
> # function body to be defined
>
> }
>
> Is this a correct header for a function?
>
> How could I do better?
>
> Kind regards
>
> Georg
>
> ______________________________________________
> R-help op r-project.org mailing list -- To UNSUBSCRIBE and more, see
> https://stat.ethz.ch/mailman/listinfo/r-help
> PLEASE do read the posting guide http://www.R-project.org/
> posting-guide.html
> and provide commented, minimal, self-contained, reproducible code.
>

	[[alternative HTML version deleted]]