document generate_man_pages.R

R/generate_man_pages.R

@@ -1,4 +1,14 @@
-# Function to format content in Rd syntax
+#' Format RD Block Content for .Rd Files
+#'
+#' This function takes an RD block extracted from a C++ or a header file, parses its 
+#' components, and formats it into a string suitable for inclusion in an `.Rd` 
+#' documentation file.
+#'
+#' @param rd_block A string containing the raw RD block extracted from a C++ or a header file.
+#'
+#' @return A formatted string representing the content of the `.Rd` file, 
+#' including sections such as `@title`, `@description`, `@param`, `@return`, 
+#' and `@examples`.
 format_rd_content <- function(rd_block) {
   rd_content <- ""
 
@@ -43,7 +53,27 @@ format_rd_content <- function(rd_block) {
   return(rd_content)
 }
 
-# Function to extract RD tags from a C++ file and write Rd files
+#' Process a C++ File to Extract RD Blocks
+#'
+#' This function reads a specified C++ file, searches for RD blocks
+#' (documentation comments) within the file, and writes the extracted
+#' and formatted RD content to an `.Rd` file in the `man/` directory.
+#'
+#' @param file_path A string specifying the path to the C++ file to be processed.
+#'
+#' @details
+#' The function identifies RD blocks in three formats:
+#' - Block comments: `/** @rd ... */`. 
+#' - Line comments: `// @rd ...`
+#' - Line comments with a single quote: `//' @rd ...`
+#' 
+#' After extracting these blocks, it saves the results in an `.Rd` file named 
+#' after the function name extracted from the `@name` tag within the RD block. 
+#' If no RD blocks are found, the function will output a message indicating this.
+#'
+#' @examples \dontrun{
+#' process_cpp_file("my_cpp_file.cpp")
+#' }
 process_cpp_file <- function(file_path) {
   cpp_content <- readr::read_lines(file_path)
   cpp_content <- paste(cpp_content, collapse = "\n")
@@ -80,7 +110,25 @@ process_cpp_file <- function(file_path) {
   }
 }
 
-# Function to recursively parse all C++ files in a directory
+#' Process C++ and Header Files in a Directory
+#'
+#' This function processes all `.cpp` and `.hpp` files within a specified
+#' directory, including subdirectories, by applying the `process_cpp_file`
+#' function to each file. It searches for RD blocks in the files and generates
+#' corresponding `.Rd` files.
+#'
+#' @param dir_path A string specifying the path to the directory containing C++ 
+#' and header files.
+#'
+#' @details
+#' The function uses the `fs::dir_ls` function to list all `.cpp` and `.hpp`
+#' files within the directory and its subdirectories. It then processes each 
+#' file individually, extracting and formatting RD blocks and creating `.Rd`
+#' files.
+#'
+#' @examples \dontrun{
+#' process_directory("inst/include/interface/rcpp")
+#' }
 process_directory <- function(dir_path) {
   cpp_files <- fs::dir_ls(dir_path, recurse = TRUE, glob = "*.cpp")