Menggunakan roxygen2 dan doxygen dalam satu paket? [Tutup]

Saya memiliki Rpaket yang menggunakan roxygen2. Ini memiliki beberapa Ckode /src, dan saya baru saja mulai bekerja dengan Doxygen. Apakah ada cara untuk menggabungkan dokumentasi, atau mengintegrasikan kompilasi dengan roxygen2? Adakah "praktik terbaik" untuk tempat meletakkan Cdokumentasi kode?

Googling untuk roxygen2 dan doxygen terutama mengarah ke roxygen mirip dengan hasil doxygen . Saya telah menemukan beberapa paket dengan Doxyfiles, tetapi tidak ada organisasi yang konsisten. Misalnya, lme4 memiliki inst/doc/Doxyfilekeluaran ke folder yang disebut di doxygenluar lme4direktori sumber. Ada juga Doxyfile di direktori root Matrix (tetapi dalam rilis sebelumnya ada di inst. Dokumentasi ini juga diekspor ke luar direktori paket.

Apakah ada alasan untuk tidak menyertakan Cdokumentasi di dalam paket, atau mengapa Doxygen sangat jarang digunakan di dalam paket R, meskipun digunakan secara luas C?

update: lihat permintaan fitur roxygen2 terkait

Saya pribadi menggunakan kode berikut dalam paket "dataManagement" yang saya panggil di semua skrip saya. Ini memiliki dokumentasi dan contoh roxygen. Anda sebenarnya cukup memanggil document () dan menjalankan doxygen pada kode C, di src /. Doc sudah dimasukkan ke inst / doxygen sehingga paket Anda sudah siap CRAN.

Dokumentasi R dirancang untuk pengguna akhir R yang tidak seharusnya melihat kode C. Saya tidak mengintegrasikan dokumentasi kode C dalam dokumentasi R klasik tetapi mungkin akan menjadi praktik yang baik untuk menyalin dokumentasi C yang dihasilkan sebagai "sketsa" .

    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","SURE\t= 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()
    }