[R] Documenting a function using roxygen2

[Jeff Newmiller]

I was under the impression that the comment block is attached to the global object that immediately follows the comment block, so this placement is NOT optional.
-- 
Sent from my phone. Please excuse my brevity.

On October 11, 2016 6:46:51 AM PDT, Thierry Onkelinx <thierry.onkelinx at inbo.be> wrote:
>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 at 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 at 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]]
>
>______________________________________________
>R-help at 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.