Документирование расширения статистики ggplot2 — devtools::document() не создает packagename-ggproto.Rd

Я создаю пакет, который будет содержать новую статистику ggplot2.

Я использую ggplot2::ggproto для создания новой статистики, но у меня проблемы с документацией по roxygen2. После запуска devtools::document() я получил:

mypackagename-ggproto.Rd отсутствует имя/название. Пропуская

Я пытался следовать примерам других пакетов (например, здесь, здесь и здесь), но у меня возникла та же проблема. В качестве минимального воспроизводимого примера я предоставляю следующее содержимое моего файла stat-test.R:

#' @title My Statistic
#'
#' @description blah blah
#'
#' @param ... other arguments.
#' @param na.rm a logical value indicating ...
#'
#' @export
#' 
stat_test <- function(mapping = NULL, data = NULL, geom = "segment", 
                     position = "identity", na.rm = FALSE, 
                     linetype="dotted", show.legend = NA, 
                     inherit.aes = TRUE, ...) {
  ggplot2::layer(
    stat = StatTEST, 
    data = data, 
    mapping = mapping, 
    geom = geom, 
    position = position, 
    show.legend = show.legend, 
    inherit.aes = inherit.aes,
    params = list(na.rm = na.rm, linetype = linetype, ...)
  )
}

#' @rdname mypackagename-ggproto
#' @format NULL
#' @usage NULL
#' @export
StatTEST <- ggplot2::ggproto("StatTEST", ggplot2::Stat,
                       compute_group = function(data, scales, ...) {
                         ## Compute the line segment endpoints

                         data[nrow(data), c("from", "to")] <- 
                           c(
                             data[1, "from"], data[1, "to"]
                             )

                         x = data[data$from, 1]
                         y = data[data$from, 2]
                         xend = data[data$to, 1]
                         yend = data[data$to, 2]

                         data.frame(x=x, y=y, xend=xend, yend=yend)

                       },
                       required_aes = c("x", "y", "from", "to")
 )

Я также прочитал виньетку roxygen2 Generating Rd Files. , но решения не нашел. Я не могу понять, почему #' @rdname mypackagename-ggproto не создает мой файл mypackagename-ggproto.Rd.

Буду признателен за любую помощь.

Информация о свидании:

R version 3.5.1 (2018-07-02)
Platform: x86_64-suse-linux-gnu (64-bit)
Running under: openSUSE Leap 15.0

Matrix products: default
BLAS: /usr/lib64/R/lib/libRblas.so
LAPACK: /usr/lib64/R/lib/libRlapack.so

locale:
 [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C               
LC_TIME=en_US.UTF-8        LC_COLLATE=en_US.UTF-8     
LC_MONETARY=en_US.UTF-8   
 [6] LC_MESSAGES=en_US.UTF-8    LC_PAPER=en_US.UTF-8       LC_NAME=C                  
LC_ADDRESS=C               LC_TELEPHONE=C            
[11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
[1] emstreeR_1.0

loaded via a namespace (and not attached):
 [1] Rcpp_0.12.18         pillar_1.3.0         compiler_3.5.1       
plyr_1.8.4           bindr_0.1.1          tools_3.5.1          
digest_0.6.15       
 [8] memoise_1.1.0        tibble_1.4.2         gtable_0.2.0         
pkgconfig_2.0.1      rlang_0.2.1          rstudioapi_0.7       
commonmark_1.5      
[15] yaml_2.2.0           bindrcpp_0.2.2       withr_2.1.2          
dplyr_0.7.6          stringr_1.3.1        roxygen2_6.1.0       xml2_1.2.0          
[22] desc_1.2.0           devtools_1.13.6      rprojroot_1.3-2      
grid_3.5.1           tidyselect_0.2.4     scatterplot3d_0.3-41 glue_1.3.0          
[29] R6_2.2.2             ggplot2_3.0.0        purrr_0.2.5          
magrittr_1.5         backports_1.1.2      scales_0.5.0         
assertthat_0.2.0    
[36] colorspace_1.3-2     stringi_1.2.4        lazyeval_0.2.1       
munsell_0.5.0        crayon_1.3.4

person allanvc    schedule 18.09.2018    source источник
comment
Вы пытались создать фиктивный файл документации, документируя NULL и устанавливая информативное @name. Затем использовать @rdname для ссылки на это?   -  person divibisan    schedule 19.09.2018
comment
Я пробовал использовать @name вместо @title. Это то, что вы имели ввиду?   -  person allanvc    schedule 19.09.2018
comment
Я не проверял это, но в виньетке Generating Rd files кажется, что вы можете использовать @rdname только для связывания документации функции с уже существующим файлом документа, а не для создания нового. Они используют его двумя способами: 1) @rdname add для документирования с помощью обычно документированной функции add и 2) @rdname arith для документирования в фиктивном файле документа, состоящем из NULL (без функции), созданного с помощью @name arith. Найдите @rdname arith, чтобы увидеть пример   -  person divibisan    schedule 19.09.2018
comment
@divibisan Хорошо, я понимаю, что вы имеете в виду, но вы видели примеры из существующих пакетов? Кажется, они используют первый способ. Попробую второй и посмотрю, что у меня получится.   -  person allanvc    schedule 19.09.2018
comment
@divisiban Думаю, это работает, когда я следую твоему совету. Я не заметил, чтобы примеры других пакетов также создавали новые геометрии. И они сначала документировали ggroto-объекты в файлах geom .R, что не относится к моему случаю. Я только создаю новую статистику. Поэтому я задокументировал NULL после stat_test() и установил информативное имя mypackagename-ggproto, как вы сказали. После этого я задокументировал объект StatTEST. Пожалуйста, опубликуйте свое предложение в качестве ответа, и я приму его. Я также отредактирую его, добавив полный код для будущих посетителей.   -  person allanvc    schedule 19.09.2018


Ответы (1)


Тег @rdname связывает документацию функции с уже существующим файлом документа, который нельзя использовать для создания нового. Если вы посмотрите на Создание виньетки файлов Rd, вы увидим, что они всегда используют @rdname, чтобы связать документацию функции с существующим файлом:

В приведенном ниже примере функция add задокументирована нормально. При использовании @rdname add функция times будет задокументирована в том же файле, что и add.

#' Basic arithmetic
#'
#' @param x,y numeric vectors.
add <- function(x, y) x + y

#' @rdname add
times <- function(x, y) x * y

Если вы не хотите создавать файл документации вокруг одной функции, вам все равно нужно создать файл, прежде чем использовать @rdname для связывания с ним функций. Вы можете сделать это, создав и задокументировав фиктивную функцию с помощью тега @name. Затем вы можете использовать @rdname для документирования функций в том же фиктивном файле:

#' Basic arithmetic
#'
#' @param x,y numeric vectors.
#' @name arith
NULL

#' @rdname arith
add <- function(x, y) x + y

#' @rdname arith
times <- function(x, y) x * y
person divibisan    schedule 19.09.2018