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
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]]
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.