c-在同一个包上使用roxygen2和doxygen

Question

我有一个使用roxygen2的R包。它在/src中有一些C代码，我刚刚开始使用Doxygen。有什么方法可以将文档结合起来或将编译与roxygen2集成起来吗？任何"；最佳实践"；C代码文档放在哪里？

谷歌搜索roxygen2和doxygen主要导致roxygen与doxygen结果相似。我发现了一些带有Doxyfiles的包，但没有一致的组织。例如，lme4将inst/doc/Doxyfile输出到lme4源目录外名为doxygen的文件夹。在Matrix的根目录中也有一个Doxyfile(但在以前的版本中是在inst中)。此文档也导出到包目录之外。

是否有任何理由不将C文档包含在软件包中，或者为什么尽管广泛使用C，但Doxygen在R软件包中却很少使用？

更新：请参阅相关的roxygen2功能请求

Answer 1

我个人在所有脚本中调用的"dataManagement"包中使用以下代码。它有roxygen文档和示例。你实际上只是简单地打电话文档()让doxygen在C代码上运行src/.文档已放入inst/doxygen这样你的包裹就可以用CRAN了。

为R最终用户设计的R文档不应该查看C代码。我没有将C代码文档集成到经典的R文档中，但将生成的C文档作为"小插曲"复制可能是一种很好的做法。

library("testthat")
library("devtools")
#' @title Replace a value for a given tag on file in memory
#' @description Scan the lines and change the value for the named tag if one line has this tag, 
#'    add a line at the end if no line has this tag and return a warning if several lines
#'    matching the tag
#' @param fileStrings A vector with each string containing a line of the file
#' @param tag The tag to be searched for 
#' @param newVal The new value for the tag
#' @return The vector of strings with the new value
#' @examples
#' fakeFileStrings <- c("Hello = world","SUREt= indeed","Hello = you")
#' 
#' expect_warning(ReplaceTag(fakeFileStrings,"Hello","me"))
#' 
#' newFake <- ReplaceTag(fakeFileStrings,"SURE","me")
#' expect_equal(length(newFake), length(fakeFileStrings))
#' expect_equal(length(grep("SURE",newFake)), 1)
#' expect_equal(length(grep("me",newFake)), 1)
#' 
#' newFake <- ReplaceTag(fakeFileStrings,"Bouh","frightened?")
#' expect_equal(length(newFake), length(fakeFileStrings)+1)
#' expect_equal(length(grep("Bouh",newFake)), 1)
#' expect_equal(length(grep("frightened?",newFake)), 1)
ReplaceTag <- function(fileStrings,tag,newVal){
iLine <- grep(paste0("^",tag,"\>"),fileStrings)
nLines <- length(iLine)
if(nLines == 0){
line <- paste0(tag,"t= ",newVal)
iLine <- length(fileStrings)+1
}else if (nLines > 0){
line <- gsub("=.*",paste0("= ",newVal),fileStrings[iLine])
if(nLines >1){
warning(paste0("File has",nLines,"for key",tag,"check it up manually"))
}
}
fileStrings[iLine] <- line
return(fileStrings)
}
#' Prepares the R package structure for use with doxygen
#' @description Makes a configuration file in inst/doxygen
#'     and set a few options: 
#'     itemize{
#'        item{EXTRACT_ALL = YES}
#'        item{INPUT = src/}
#'        item{OUTPUT_DIRECTORY = inst/doxygen/}
#'     }
#' @param rootFolder The root of the R package
#' @return NULL
#' @examples 
#' dontrun{
#' DoxInit()
#' }
#' @export
DoxInit <- function(rootFolder="."){
doxyFileName <- "Doxyfile"
initFolder <- getwd()
if(rootFolder != "."){
setwd(rootFolder)
}
rootFileYes <- length(grep("DESCRIPTION",dir()))>0
# prepare the doxygen folder
doxDir <- "inst/doxygen"
if(!file.exists(doxDir)){
dir.create(doxDir,recursive=TRUE)
}
setwd(doxDir)
# prepare the doxygen configuration file
system(paste0("doxygen -g ",doxyFileName))
doxyfile <- readLines("Doxyfile")
doxyfile <- ReplaceTag(doxyfile,"EXTRACT_ALL","YES")
doxyfile <- ReplaceTag(doxyfile,"INPUT","src/")
doxyfile <- ReplaceTag(doxyfile,"OUTPUT_DIRECTORY","inst/doxygen/")
cat(doxyfile,file=doxyFileName,sep="n")
setwd(initFolder)
return(NULL)
}
#' devtools document function when using doxygen
#' @description Overwrites devtools::document() to include the treatment of 
#'    doxygen documentation in src/
#' @param doxygen A boolean: should doxygen be ran on documents in src?
#'     the default is TRUE if a src folder exist and FALSE if not
#' @return The value returned by devtools::document()
#' @example
#' dontrun{
#' document()
#' }
#' @export
document <- function(doxygen=file.exists("src")){
if(doxygen){
doxyFileName<-"inst/doxygen/Doxyfile"
if(!file.exists(doxyFileName)){
DoxInit()
}
system(paste("doxygen",doxyFileName))
}
devtools::document()
}