Convert to roxygen2 (#263)

* Convert .Rd to roxygen2

* Convert roxygen2 to md

* Convert lists

* Add missing `@rdname` tags

* Generate namespace with roxygen2

* improve wrapping

* add a verbal example.

* keep organization grouping of data.table imports

Co-authored-by: Michael Chirico <michaelchirico4@gmail.com>

Author: hadley

NAMESPACE

@@ -1,25 +1,49 @@
-importFrom(data.table, data.table, foverlaps, fread, rbindlist, uniqueN, chmatch, "%chin%")
-importFrom(data.table, is.data.table, as.data.table)
-importFrom(data.table, copy, set, setattr, setcolorder, setDT, setindexv, setkeyv, setnafill, setnames, setorderv)
-importFrom(data.table, `:=`, .BY, .N, .SD)
-importFrom(data.table, fcase, fifelse, shift, tstrsplit)
+# Generated by roxygen2: do not edit by hand
 
-importFrom(stats, setNames)
-importFrom(utils, getParseData, globalVariables, head, tail, type.convert)
-
-export(translate_package)
+S3method(all,equal.specials_metadata)
+S3method(format,po_metadata)
+S3method(format,specials_metadata)
+S3method(print,po_metadata)
+export(check_cracked_messages)
+export(check_potools_sys_reqs)
+export(check_untranslated_cat)
+export(check_untranslated_src)
 export(get_message_data)
-export(write_po_file, po_metadata)
-
-export(po_extract)
 export(po_compile)
-
-export(check_cracked_messages, check_untranslated_cat, check_untranslated_src)
-
-export(check_potools_sys_reqs)
-
-S3method(format, specials_metadata)
-S3method(all.equal, specials_metadata)
-
-S3method(format, po_metadata)
-S3method(print, po_metadata)
+export(po_extract)
+export(po_metadata)
+export(translate_package)
+export(write_po_file)
+importFrom(data.table,"%chin%")
+importFrom(data.table,.BY)
+importFrom(data.table,.N)
+importFrom(data.table,.SD)
+importFrom(data.table,`:=`)
+importFrom(data.table,as.data.table)
+importFrom(data.table,chmatch)
+importFrom(data.table,copy)
+importFrom(data.table,data.table)
+importFrom(data.table,fcase)
+importFrom(data.table,fifelse)
+importFrom(data.table,foverlaps)
+importFrom(data.table,fread)
+importFrom(data.table,is.data.table)
+importFrom(data.table,rbindlist)
+importFrom(data.table,set)
+importFrom(data.table,setDT)
+importFrom(data.table,setattr)
+importFrom(data.table,setcolorder)
+importFrom(data.table,setindexv)
+importFrom(data.table,setkeyv)
+importFrom(data.table,setnafill)
+importFrom(data.table,setnames)
+importFrom(data.table,setorderv)
+importFrom(data.table,shift)
+importFrom(data.table,tstrsplit)
+importFrom(data.table,uniqueN)
+importFrom(stats,setNames)
+importFrom(utils,getParseData)
+importFrom(utils,globalVariables)
+importFrom(utils,head)
+importFrom(utils,tail)
+importFrom(utils,type.convert)

R/check_cracked_messages.R

@@ -1,5 +1,46 @@
 # check for calls like stop("a", i, "b", j) that are better suited for
 #   translation as calls like gettextf("a%db%d", i, j)
+
+
+#' Check for cracked messages more suitable for templating
+#'
+#' Diagnose the R messages in a package to discover the presence of "cracked"
+#' messages better served for translation by templating. See Details.
+#'
+#'
+#' Error messages built like
+#' `stop("You gave ", n, " arguments, but ", m, " are needed.")` are
+#' in general hard for translators -- the correct
+#' translation may be in a totally different order (e.g., this is often the
+#' case for Japanese). It is preferable instead to use
+#' [base::gettextf()] to build a templated message like
+#' `stop(gettextf("You gave %d arguments but %d are needed.", n, m))`.
+#' Translators are then free to rearrange the template to put the numeric
+#' pattern where it fits most naturally in the target language.
+#'
+#' @param message_data A `data.table`, or object convertible to one.
+#' @return A `data.table` with columns `call`, `file`,
+#' `line_number`, and `replacement` summarizing the results.
+#' @author Michael Chirico
+#' @seealso [translate_package()], [update_pkg_po()]
+#' @examples
+#'
+#' pkg <- file.path(system.file(package = 'potools'), 'pkg')
+#' # copy to a temporary location to be able to read/write/update below
+#' tmp_pkg <- file.path(tempdir(), "pkg")
+#' dir.create(tmp_pkg)
+#' file.copy(pkg, dirname(tmp_pkg), recursive = TRUE)
+#'
+#' # first, extract message data
+#' message_data = get_message_data(tmp_pkg)
+#'
+#' # now, diagnose the messages for any "cracked" ones
+#' check_cracked_messages(message_data)
+#'
+#' # cleanup
+#' unlink(tmp_pkg, recursive = TRUE)
+#' rm(pkg, tmp_pkg, message_data)
+#' @export
 check_cracked_messages = function(message_data) {
   if (!is.data.table(message_data)) message_data = as.data.table(message_data)
 

R/check_untranslated_cat.R

@@ -1,5 +1,57 @@
 # check a package for calls to cat() that have untranslated strings (i.e.,
 #   aren't passed through gettext or ngettext)
+
+
+#' Check for untranslated messages emitted by cat
+#'
+#' Diagnose the R messages in a package to discover the presence of messages
+#' emitted by [cat()] which haven't been translated (i.e., passed
+#' through [gettext()], [gettextf()], or
+#' [ngettext()]).
+#'
+#'
+#' The function `cat` is commonly used to emit messages to users (e.g.,
+#' for a `verbose` mode), but it is not equipped for translation. Instead,
+#' messages must first be translated and then emitted. Any character literals
+#' found in the package's R code used in `cat` but not translated will be
+#' flagged by this function.
+#'
+#' For flagged calls, a potential replacement is offered, built using
+#' `gettext` or `gettextf` (depending on whether one or more
+#' `...` arguments are supplied to `cat`). For the `gettextf`
+#' case, the suggested template is always `%s` (string) since this works
+#' for all inputs; the author should tighten this to the appropriate
+#' [sprintf()] template marker as appropriate, for example if the author
+#' knows the input is an integer, use `%d` or `%i` instead of `%s`.
+#'
+#' NB: not all `cat` calls are included -- in particular, no `cat`
+#' call specifying a non-default `file` are flagged, nor are any where the
+#' supplied `sep` is not a character literal (e.g., `sep=x` instead
+#' of `sep=""`)
+#'
+#' @param message_data A `data.table`, or object convertible to one.
+#' @return A `data.table` with columns `call`, `file`,
+#' `line_number`, and `replacement` summarizing the results.
+#' @author Michael Chirico
+#' @seealso [translate_package()], [update_pkg_po()]
+#' @examples
+#'
+#' pkg <- file.path(system.file(package = 'potools'), 'pkg')
+#' # copy to a temporary location to be able to read/write/update below
+#' tmp_pkg <- file.path(tempdir(), "pkg")
+#' dir.create(tmp_pkg)
+#' file.copy(pkg, dirname(tmp_pkg), recursive = TRUE)
+#'
+#' # first, extract message data
+#' message_data = get_message_data(tmp_pkg)
+#'
+#' # now, diagnose the messages for any untranslated strings shown through cat()
+#' check_untranslated_cat(message_data)
+#'
+#' # cleanup
+#' unlink(tmp_pkg, recursive = TRUE)
+#' rm(pkg, tmp_pkg, message_data)
+#' @export
 check_untranslated_cat <- function (message_data) {
   if (!is.data.table(message_data)) message_data = as.data.table(message_data)
   # not iron-clad but it's a good first pass

R/check_untranslated_src.R

@@ -1,5 +1,46 @@
 # check a package for character arrays in messaging functions that
 #   haven't been passed through the translation macro
+
+
+#' Check for cracked messages in C/C++ sources
+#'
+#' Diagnose the C/C++ messages in a package to discover untranslated messages
+#'
+#'
+#' This diagnostic looks for literal `char` arrays passed to messaging
+#' functions (as identified by [translate_package()]) which are not
+#' marked for translation (by tagging them for translation with `_` or
+#' `N_` macros). These strings cannot be translated until they are so
+#' marked.
+#'
+#' @param message_data A `data.table`, or object convertible to one.
+#' @return A `data.table` with columns `call`, `file`,
+#' `line_number`, and `replacement` summarizing the results.
+#' `replacement` is `NA` at this time, i.e., no replacement is
+#' provided.
+#' @author Michael Chirico
+#' @seealso [translate_package()], [update_pkg_po()]
+#' @examples
+#'
+#' pkg <- file.path(system.file(package = 'potools'), 'pkg')
+#' # copy to a temporary location to be able to read/write/update below
+#' tmp_pkg <- file.path(tempdir(), "pkg")
+#' dir.create(tmp_pkg)
+#' file.copy(pkg, dirname(tmp_pkg), recursive = TRUE)
+#'
+#' # first, extract message data
+#' message_data = get_message_data(
+#'   tmp_pkg,
+#'   custom_translation_functions = list(src = "ReverseTemplateMessage:2")
+#' )
+#'
+#' # now, diagnose the messages for any untranslated messages in C/C++
+#' check_untranslated_src(message_data)
+#'
+#' # cleanup
+#' unlink(tmp_pkg, recursive = TRUE)
+#' rm(pkg, tmp_pkg, message_data)
+#' @export
 check_untranslated_src <- function (message_data) {
   if (!is.data.table(message_data)) message_data = as.data.table(message_data)
 

R/get_message_data.R

@@ -1,57 +1,63 @@
 #' Extract user-visible messages from a package
 #'
 #' This function looks in the R and src directories of a package for
-#' user-visible messages and compiles them as a [data.table::data.table()]
-#' to facilitate analyzing this corpus as such.
+#' user-visible messages and compiles them as a
+#' [data.table::data.table()] to facilitate
+#' analyzing this corpus as such.
 #'
-#' @param dir Character, default the present directory; a directory in which
-#'   an R package is stored.
+#'
+#' @param dir Character, default the present directory; a directory in which an
+#' R package is stored.
 #' @param custom_translation_functions A `list` with either/both of two
-#'   components, `R` and `src`, together governing how to extract any
-#'   non-standard strings from the package.
+#' components, `R` and `src`, together governing how to extract any
+#' non-standard strings from the package.
 #'
-#'   See Details in [translate_package()].
+#' See Details in [`translate_package()`][translate_package].
 #' @param style Translation style, either `"base"` or `"explict"`.
-#'   The default, `NULL`, reads from the `DESCRIPTION` field
-#'   `Config/potools/style` so you can specify the style once for your
-#'   package.
+#' The default, `NULL`, reads from the `DESCRIPTION` field
+#' `Config/potools/style` so you can specify the style once for your
+#' package.
 #'
-#'   Both styles extract strings explicitly flagged for translation with
-#'   `gettext()` or `ngettext()`. The base style additionally extracts
-#'   strings in calls to `stop()`, `warning()`, and `message()`,
-#'   and to `stopf()`, `warningf()`, and `messagef()` if you have
-#'   added those helpers to your package. The explicit style also accepts
-#'   `tr_()` as a short hand for `gettext()`. See
-#'   `vignette("developer")` for more details.
+#' Both styles extract strings explicitly flagged for translation with
+#' `gettext()` or `ngettext()`. The base style additionally extracts
+#' strings in calls to `stop()`, `warning()`, and `message()`,
+#' and to `stopf()`, `warningf()`, and `messagef()` if you have
+#' added those helpers to your package. The explicit style also accepts
+#' `tr_()` as a short hand for `gettext()`. See
+#' `vignette("developer")` for more details.
 #' @param verbose Logical, default `TRUE` (except during testing). Should
-#'   extra information about progress, etc. be reported?
-#' @return A `data.table` with the following schema:
+#' extra information about progress, etc. be reported?
+#' @return
+#' A `data.table` with the following schema:
 #'
-#' * `message_source`, `character`, either `"R"`
-#'   or `"src"`, saying whether the string was found in the R or the src
-#'   folder of the package
-#' * `type`, `character`, either `"singular"` or `"plural"`;
-#'   `"plural"` means the string came from [ngettext()] and can be pluralized
-#' * `file`, `character`, the file where the string was found
-#' * `msgid`, `character`, the string (character literal or `char` array as
+#' * `message_source`: `character`, either `"R"` or `"src"`,
+#'   saying whether the string was found in the R or the src folder of the
+#'   package
+#' * `type`: `character`, either `"singular"` or
+#'   `"plural"`; `"plural"` means the string came from
+#'   [`ngettext()`][ngettext] and can be pluralized
+#' * `file`: `character`, the file where the string was found
+#' * `msgid`: `character`, the string (character literal or `char` array as
 #'   found in the source); missing for all `type == "plural"` strings
-#' * `msgid_plural`, `list(character, character)`, the strings
+#' * `msgid_plural`: `list(character, character)`, the strings
 #'   (character literals or `char` arrays as found in the source); the first
 #'   applies in English for `n=1` (see `ngettext`), while the second
 #'   applies for `n!=1`; missing for all `type == "singular"` strings
-#' * `call`, `character`, the full call containing the string
+#' * `call`: `character`, the full call containing the string
 #'   that was found
-#' * `line_number`, `integer`, the line in `file` where the string was found
-#' * `is_repeat`, `logical`, whether the `msgid` is a duplicate within this
+#' * `line_number`: `integer`, the line in `file` where the string was found
+#' * `is_repeat`: `logical`, whether the `msgid` is a duplicate within this
 #'   `message_source`
-#' *  `is_marked_for_translation`, `logical`, whether the string is marked for
-#'    translation (e.g., in R, all character literals supplied to a `...`
-#'    argument in [stop()] are so marked)
-#' *  `is_templated`, `logical`,whether the string is templatable (e.g., uses
-#'    `%s` or other formatting markers)
+#' * `is_marked_for_translation`:`logical`, whether the string is marked for
+#'   translation (e.g., in R, all character literals supplied to a `...` argument in
+#'   [`stop()`][stop] are so marked)
+#' * `is_templated`, `logical`, whether the string is templatable (e.g., uses
+#'   `%s` or other formatting markers)
 #' @author Michael Chirico
-#' @seealso [translate_package()], [write_po_file()]
+#' @seealso [`translate_package()`][translate_package],
+#' [`write_po_file()`][write_po_file]
 #' @examples
+#'
 #' pkg <- system.file('pkg', package = 'potools')
 #' get_message_data(pkg)
 #'
@@ -67,6 +73,8 @@
 #'
 #' # cleanup
 #' rm(pkg)
+#'
+#' @export
 get_message_data = function(
   dir = ".",
   custom_translation_functions = list(R = NULL, src = NULL),

R/po_compile.R

@@ -1,14 +1,17 @@
 #' Compile `.po` files to `.mo`
 #'
-#' This function compiles the plain text `.po` files that translators work with
-#' into the binary `.mo` files that are installed with packages and used for
-#' live translations.
+#' This function compiles the plain text `.po` files that translators work
+#' with into the binary `.mo` files that are installed with packages and
+#' used for live translations.
+#'
 #'
 #' @param dir Path to package root directory.
-#' @param package Name of package. If not supplied, read from `DESCRIPTION`.
-#' @param lazy If `TRUE`, only `.mo` functions that are older than `.po`
-#'   files be updated
+#' @param package Name of package. If not supplied, read from
+#' `DESCRIPTION`.
+#' @param lazy If `TRUE`, only `.mo` functions that are older than
+#' `.po` files be updated
 #' @param verbose If `TRUE`, print information as it goes.
+#' @export
 po_compile = function(dir = ".", package = NULL, lazy = TRUE, verbose = TRUE) {
   po_metadata <- get_po_metadata(dir = dir, package = package)
   dir_create(dirname(po_metadata$mo))

R/po_extract.R

@@ -1,13 +1,35 @@
 #' Extract messages for translation into a `.pot` file
 #'
 #' `po_extract()` scans your package for strings to be translated and
-#' saves them into a `.pot` template file (in the package's `po` directory).
-#' You should never modify this file by hand; instead modify the underlying
-#' source code and re-run `po_extract()`.
+#' saves them into a `.pot` template file (in the package's `po`
+#' directory). You should never modify this file by hand; instead modify the
+#' underlying source code and re-run `po_extract()`.
 #'
-#' @returns The extracted messages as computed by [get_message_data()],
-#'   invisibly.
-#' @inheritParams get_message_data
+#'
+#' @param dir Character, default the present directory; a directory in which an
+#' R package is stored.
+#' @param custom_translation_functions A `list` with either/both of two
+#' components, `R` and `src`, together governing how to extract any
+#' non-standard strings from the package.
+#'
+#' See Details in [`translate_package()`][translate_package].
+#' @param verbose Logical, default `TRUE` (except during testing). Should
+#' extra information about progress, etc. be reported?
+#' @param style Translation style, either `"base"` or `"explict"`.
+#' The default, `NULL`, reads from the `DESCRIPTION` field
+#' `Config/potools/style` so you can specify the style once for your
+#' package.
+#'
+#' Both styles extract strings explicitly flagged for translation with
+#' `gettext()` or `ngettext()`. The base style additionally extracts
+#' strings in calls to `stop()`, `warning()`, and `message()`,
+#' and to `stopf()`, `warningf()`, and `messagef()` if you have
+#' added those helpers to your package. The explicit style also accepts
+#' `tr_()` as a short hand for `gettext()`. See
+#' `vignette("developer")` for more details.
+#' @return The extracted messages as computed by
+#' [`get_message_data()`][get_message_data], invisibly.
+#' @export
 po_extract <- function(
     dir = ".",
     custom_translation_functions = list(),